{"id":411347,"date":"2024-06-29T21:54:50","date_gmt":"2024-06-29T21:54:50","guid":{"rendered":"http:\/\/savepearlharbor.com\/?p=411347"},"modified":"-0001-11-30T00:00:00","modified_gmt":"-0001-11-29T21:00:00","slug":"","status":"publish","type":"post","link":"https:\/\/savepearlharbor.com\/?p=411347","title":{"rendered":"Simple text markup internationalization (i18n)<\/span>"},"content":{"rendered":"
<\/div>\n
\n
\n
\n
\n

\"xrjzpblczowgylzxmvefrjjt4og\"<\/p>\n

<\/a> <\/p>\n

Introduction<\/h1>\n

<\/p>\n

\u041f\u0435\u0440\u0435\u0439\u0442\u0438 \u043a \u0440\u0443\u0441\u0441\u043a\u043e\u0439 \u0432\u0435\u0440\u0441\u0438\u0438<\/a><\/p>\n

<\/p>\n

Several years ago my colleague posted an article<\/a> about making presentations in Asciidoctor<\/a>. Since then, we don’t use any other approach.<\/p>\n

<\/p>\n

Some time ago there have appeared a problem of translating presentations into several languages and have them synchronized. The solution appeared to be so simple and mature that I decided to describe it in this post.<\/p>\n

<\/p>\n

This solution is syntax-unaware. This means, it doesn’t matter whether we use Asciidoc, other light text markup or even mixed format (with my favourite Plantuml or any other diagrams, for example). The serious limitations of this approach are (1) the translator shouldn’t break markup structure and (2) we can’t directly apply machine translation to the original text.<\/p>\n

<\/p>\n

The solution uses Translation Toolkit<\/a> and standard GNU Gettext tools<\/a>.<\/p>\n

<\/p>\n

To make this solution clear this article has English and Russian versions. Its repository<\/a> contains some simple automation that synchronizes translation, creates printing version (pdf, docx, odt) and creates Markdown file for publishing to Habr.<\/p>\n

<\/p>\n

In my recent article on testing documentation I didn’t pay much attention to text linters, because the focus was on approaches, not exact tools. Still these tools are great. To fill the gap, I’ll use vale<\/a> for this article.<\/p>\n

<\/p>\n

The idea<\/h1>\n

<\/p>\n

Gettext assumes that key strings for translation are original messages.<\/p>\n

<\/p>\n

Gettext uses files with .po<\/code> extension (PO\u2009\u2014\u2009Portable Object<\/a>) to keep both original and translated messages. A great number of editors allow to edit such files either in a single user or collaborative environments.<\/p>\n

<\/p>\n

The idea of Translation Toolkit is to use blocks of adjacent lines as such strings.<\/p>\n

<\/p>\n

Take this example:<\/p>\n

<\/p>\n

.Winter is<\/code><\/pre>\n
  <\/p>\n
* snow * frost<\/code><\/pre>\n
  <\/p>\n
* Christmas * New Year<\/code><\/pre>\n
  <\/p>\n
It has three blocks of adjacent strings. Translation Toolkit will extract three key strings for translation and will put it to a file with the .pot<\/code> extension (.pot<\/code> stands for .po<\/code> Template).<\/p>\n
  <\/p>\n
Putting or removing line breaks in this example you may make any number of strings from 1 to 5. This depends on convenience to the translator.<\/p>\n
  <\/p>\n
Using a .pot<\/code> file as a template Gettext creates (updates) .po<\/code> files for all required languages. Translators handle exactly these files. After that Translation Toolkit takes (1) a .po<\/code> file with translation, (2) the original file and creates a final translated file.<\/p>\n
  <\/p>\n
The Process<\/h1>\n
  <\/p>\n
The process consists of the following steps.<\/p>\n
  <\/p>\n