Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Localization (reST)

From TYPO3Wiki
Jump to: navigation, search

First of all, there are basically two ways to translate your reST documentation, unfortunately both with pros and cons:

  • Translate your documentation as a separate reST project
    • Pros
      • No special software/infrastructure needs
      • Possibility of translating every single bit of content
      • SEO for URL: everything including generated file names are translated, when generating a HTML website
    • Cons
      • Staying in sync with the "master" language is tricky
      • Switching language when reading a chapter is really tricky as generated file names are translated (SEO for good and for bad)
  • Use the internationalization feature of Sphinx
    • Pros
      • One master language, overlays (as in TYPO3) over it, what is not translated yet is simply falling back to master language
      • Relatively easy to translate with Pootle
      • Switching from a version to another language is just a matter of changing a language prefix in the URL as URL segments are the same (generated file names stay in the master language) => it is straightforward to read the very same chapter in another language
    • Cons
      • Trickier to set up (Pootle for collaborative work)
      • Limitations in Sphinx may prevent you from translating absolutely everything (see below)

notice - Note

Since the switch to reStructuredText/Sphinx for official documentation, best practices have been found. Please read the corresponding chapter of the EXT:sphinx documentation.


Overview

This chapter describes how you may use the internationalization feature of Sphinx to translate your reST documentation.

Note: This tutorial is based on [1].

Extract texts to be translated:

$ make gettext

Translate .pot files in build/locale into .po using Virtaal or Pootle. Store these files into locale/source/{language-code}/{file.po}. You can (and probably should) store these files into your source version control (Git/Subversion).

Compile each file with:

$ cd /path/to/locale/source/{language-code}/
$ msgfmt file.po -o /path/to/locale/{language-code}/LC_MESSAGES/file.mo

Then update conf.py to read:

locale_dirs = ['../locale/']
language = {language-code}

where {language-code} should be a 2-letter code as found on [2]. Then recompile your documentation as usual.

Localizing Images

As for any other reST command, images are not extracted as text. A trick to change the image to be used in a language with another one is to insert images as named images instead:

.. |some_name_EN| image:: path/to/image.png
    :alt: Some text describing the image

.. |some_name_FR| image:: path/to/image_for_french.png
    :alt: Un texte pour décrire l'image

and then use |some_name_EN| as you would insert an image. Running make gettext will extract the marker |some_name_EN| and let you "translate" it to |some_name_FR|, effectively localizing the corresponding image.

(Francois (talk) 13:37, 17 February 2013 (CET)) Note: in the official documentation, we are switching to using the figure directive which will enable us (in the future) to build a table of contents of images used in a manual. The figure directive cannot be used with inclusions, so the point is rather moot. The figure directive would be translated like the rest of the content.

Localizing the Index

As you know, reST lets you create an index of terms for your documentation ([3]):

.. index::
    pair: Role; Member
    single: Role; Website editor

Currently I don't know how to properly localize such content. I tried with condition compilation ([4]) and with inline index declaration but the index (in any language) was always rendered, regardless of my settings.

Update 08.01.2013: Since this bug has been fixed in Sphinx, localization of index entries should now be possible.