5.2 Notes for backend localisers

IMPORTANT: Due to a GitBook rendering issue, all percent signs in the example code below are being replaced with ampersands. Be sure to reintroduce the percent signs when writing your own code!! Likewise, in two cases below, a set of nested curly braces has been replaced by curly braces enclosing square brackets.

The django settings file - which, for our purposes, is located in pari/pari/settings/base.py - has been modified to support localisation (as described in this tutorial and in the official django documentation), but there are several additional steps to follow when enabling localisation for the first time on your system or tagging new content for translation.

Manually create a "locales" folder where you will store your translation files. This should be located at the project root (as specified in the settings file).
To localize any new static strings that might have been introduced into the code:
- For short, simple strings (one line or less, containing no django template tags), use the following syntax:
```
{& trans "short string to be translated" &}
```
- For longer, more complicated strings (either multilline or containing django template tags) use the more versatile blocktrans tag. You can add the parameter trimmed to exclude any excess whitespace from the translation string.
```
{& blocktrans trimmed &} This is a longer chunk of text which extends across multiple lines and also contains a <a href="www.nytimes.com">link</a> to an external site (but no django template tags). {& endblocktrans &}
```
- If there is already a django template tag within the string to be translated, you'll have to factor it out of this line of code, since {& blocktrans &} is also a template tag and nested tags are prohibited. In that case, instead of:
```
{& blocktrans trimmed &} This is a longer chunk of text which extends across multiple lines and also contains a <a href={& url 'stuff/some-page' &}>link</a> to a page within the same project. {& endblocktrans &}
```
  you should write:
```
{& url 'stuff/some-page' as some_page &}`  
{& blocktrans trimmed &} This is a longer chunk of text which extends across multiple lines and also contains a <a href={[some_page]}>link</a> to a page within the same project. {& endblocktrans &}
```
  Another instance for which this construct might be useful is if you need to insert a translated string into an include tag. In that case, use the following syntax:
```
{& trans "My Scintillating Title" as my_title &}`  
{& include "somepath.html" with title={[ my_title ]} &}
```
  thus neatly avoiding any nesting issues.
Once all your static strings have been tagged for translation, run the appropriate django script to extract them and consolidate them into a translation file. For PARI developers, the following command should work:
```
python manage.py makemessages -l XYZ --extension=html
```
where XYZ refers to the language in question. XYZ should be an ISO 639.2 language code and should be included in the django settings file under LANGUAGES.

If you wish to run an abridged version of the makemessages command that will only output strings displayed on the website (no backend strings) -- which is most likely the case -- issue the following command instead:
```
pari_makemessages.sh XYZ
```
Make sure you issue this command from within the project directory and the project virtualenv:
```
vagrant ssh
cd /vagrant && source pari_env/bin/activate
```
As soon as this command is successfully executed, your translation file will appear in the XYZ subfolder of your locales directory (with a .mo extension).
If the previous step fails, it's probably because you do not have GNU gettext installed on your system. Download it here and issue the following sequence of commands from inside the unzipped file:
```
$ ./configure
$ make
$ make check
$ make install
```
Deliver the file to the appropriate translator for the target language (see section 5.1).
Once the human translation phase is complete, compile the translations by issuing the following command:
```
python manage.py compilemessages -l XYZ
```
If any compilation errors occur at this stage, they will most likely be the following:
```
a format specification for argument abcd doesn't exist in 'msgstr'
```
The offending line should be altered so that any parameters enclosed within &(...)s are also included in the translated string.
At this point, the translation should be ready for deployment. Ways of triggering different languages in production is outside the scope of these guidelines, but the simplest way to go about testing your translations is to change the LANGUAGE_CODE value in the settings file to your target language. (The language in question also needs to be "activated" in the corresponding templates.)

5.2 Notes for backend localisers

results matching ""

No results matching ""