Translation

From ago control wiki
Jump to: navigation, search

Contents

Translation of ago control

This page documents the current way of translating ago control to other languages based on the state develop branch in git at the time of writing.

Core translation files for the RPC interface

If you open the ago control web interface in your browser, the user agent's locale will determine the language used for display. If the language is not (yet) supported, the interface will fall back to the default - which is English.

The web interface located at core/rpc/html consist of template files found in the html subdirectory of each component. Each template has the ending .in.html. The translation information resides within .po files in the core/rpc/html/po directory.

The template files have a special syntax, so don't just copy a "translated" HTML to a .in.html. Always take a .in.html as template if you want to add a new file. During the build, they're merged with the .po files into the final .html files. You need to base your work on a .in.html file only. The .in.html has text bindings which will be translated.

Template translation example

If you have a look at [1] you can find the following:

<ko opts="if: state() == 0">
    <_span data-translateable="true">OFF</_span>
</ko>

So it will show "OFF" when the state is set accordingly. Take note of two things:

  • The surrounding tags are prefixed by an underscore ('_').
  • An attribute data-translateable="true" is present in the surrounding element.

After .po merge by the build (or manual triggering), this will be transformed to:

<ko opts="ifnot: state ">
    <span data-translateable="true">OFF</span>
    <span xml:lang="de" data-translateable="true">AUS</span>
    <span xml:lang="fr" data-translateable="true">OFF</span>
    <span xml:lang="nl" data-translateable="true">UIT</span>
</ko>

For each language you will get the xml:lang records with the translated content.

If you want to translate the content of an attribute, similar rules apply. For example:

<input data-translateable="true" _placeholder="Your text to translate"></input>

As you can see, the placeholder attribute is translated here. Again the two important points are:

  • The attribute has to be prefixed by an underscore ('_').
  • An attribute data-translateable="true" is present in the surrounding element.

Of course, both variants can be combined as well.

Adding a new translation template

There is file named a POTFILES.in in the core/rpc/html/po directory. This file contains a list of all files that should be handled during translation.

You are perhaps confused about the naming templates/devices/switch.xml.in. This is a requirement for the underlying intltool[2] script which handles the translation process on a lower level. The script expects to have the files named this way.

In order to include your template for translation, you just need to list your file in POTFILES.in with the real template name's .in.html replaced by .xml.in. So for example templates/devices/switch.in.html becomes templates/devices/switch.xml.in.

Next you need to call the updatetranslations.sh script located in core/rpc/html. You must run the script from exactly this directory, as it relies on some fixed path locations.

It will work through all the files listed in POTFILES.in and extract the translatable information. The result will be used to update the agocontrol.pot file (the basic translation template) and all .po files.

You now can have a look into for e.g. de.po and you will find - mostly at the end - missing translations:

#: ../plugins/zwave/templates/zwaveConfig.xml.in.h:69
msgid "Reset controller"
msgstr ""

Or even "automatic" translation which may be fuzzy (and often misleading):

#: ../plugins/zwave/templates/zwaveConfig.xml.in.h:70
#, fuzzy
msgid "Download configuration"
msgstr "Raum Konfiguration"

The translation will be entered in the msgstr lines. Please mind the original text - not to loose some special chars or something like this. After you are finished with your local translation you need merge the translation to see the result. Read on for how to do this.

If you do not want to edit the text file in a simple editor, Poedit [3] provides a very convenient cross-platform alternative.

Adding a new language

If you want to add a new language, copy the agocontrol.pot file to your language code. For example, to create a new (Hungarian) translation copy it to hu.po.

Now you can edit the file to your hearts content and it will be picked automatically the next time the translations are created.

If you have any questions or problems at this point contact us at IRC #agocontrol-devel on the freenode.net.

Triggering a manual translation for testing

The addition of the translation information is done automatically during the build. If you do not want to run a full build it is sufficient to have build environment set up as described in [4].

Inside the build directory run (for an out-of-tree build):

cmake ..

This will copy over the template files as well as the translation information to your build directory.

You need to do this step every time you have either:

  • updated a template file
  • updated a translation file

To finally merge the translations and create the HTML files do:

make -B translations

The -B options tells make to build the target unconditionally. This is unfortunately needed, as make does not recognise if files were updated. This is due to the current design of the translation process.

So when working on a translation always run the following commands (inside the build directory):

cmake .. && make -B translations

This will prevent you from surprises like I did this already, didn't I?. See also the next step for some extra convenience.

Development note for previewing the translation

Usually you will have ago control installed via a package. This will put all the files under /opt/agocontrol. So the (already translated) HTML files are stored at /opt/agocontrol/html. The naive approach would be to copy your translated files over to the installation directory.

Please do not do so. ago control provides a nice way for testing:

Just point the agorpc component to your git checkout's build directory (for example /home/user/agocontrol/build/core/rpc/html) by changing the htdocs option in /etc/opt/agocontrol/conf.d/rpc.conf:

[rpc]
# commented default location
# htdocs=/opt/agocontrol/html
htdocs=/home/user/agocontrol/build/core/rpc/html

Reload the agorpc component by issuing (as root):

systemctl restart agorpc

(Re)load the web page in your browser and check your translation. The interface files are now taken from this directory.

Personal tools