Translation

From ago control wiki
(Difference between revisions)
Jump to: navigation, search
(Created page with "= Translation of ago control = == Core translation files for RPC Interface == === translation inside Tags === <input data-translateable="true" placeholder="Your text to tra...")
 
(Update for the current translation work flow in branch develop)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= Translation of ago control =
 
= Translation of ago control =
  
== Core translation files for RPC Interface ==
+
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.
  
=== translation inside Tags ===
+
== Core translation files for the RPC interface ==
  <input data-translateable="true" placeholder="Your text to translate"></input>
+
 
 +
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 <code>core/rpc/html</code> consist of template files found in the <code>html</code> subdirectory of each component. Each template has the ending <code>.in.html</code>. The translation information resides within <code>.po</code> files in the <code>core/rpc/html/po</code> directory.
 +
 
 +
The template files have a special syntax, so don't just copy a "translated" HTML to a <code>.in.html</code>. Always take a <code>.in.html</code> as template if you want to add a new file. During the build, they're merged with the <code>.po</code> files into the final <code>.html</code> files. You need to base your work on a <code>.in.html</code> file only. The <code>.in.html</code> has text bindings which will be translated.
 +
 
 +
=== Template translation example ===
 +
 
 +
If you have a look at [http://git.agocontrol.com/agocontrol/agocontrol/blob/master/core/rpc/html/templates/devices/switch.in.html] you can find the following:
 +
 
 +
<pre>
 +
<ko opts="if: state() == 0">
 +
    <_span data-translateable="true">OFF</_span>
 +
</ko>
 +
</pre>
 +
 
 +
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 <code>data-translateable="true"</code> is present in the surrounding element.
 +
 
 +
After .po merge by the build (or manual triggering), this will be transformed to:
 +
 
 +
<pre>
 +
<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>
 +
</pre>
 +
 
 +
For each language you will get the <code>xml:lang</code> 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 <code>placeholder</code> attribute is translated here. Again the two important points are:
 +
 
 +
* The attribute has to be prefixed by an underscore ('_').
 +
* An attribute <code>data-translateable="true"</code> 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 <code>POTFILES.in</code> in the <code>core/rpc/html/po</code> directory. This file contains a list of all files that should be handled during translation.
 +
 
 +
You are perhaps confused about the naming <code>templates/devices/switch.xml.in</code>. This is a requirement for the underlying <code>intltool</code>[https://freedesktop.org/wiki/Software/intltool/] 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 <code>POTFILES.in</code> with the real template name's <code>.in.html</code> replaced by <code>.xml.in</code>. So for example <code>templates/devices/switch.in.html</code> becomes <code>templates/devices/switch.xml.in</code>.
 +
 
 +
Next you need to call the <code>updatetranslations.sh</code> script located in <code>core/rpc/html</code>. '''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 <code>POTFILES.in</code> and extract the translatable information. The result will be used to update the <code>agocontrol.pot</code> file (the basic translation template) and all <code>.po</code> files.
 +
 
 +
You now can have a look into for e.g. <code>de.po</code> 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 <code>msgstr</code> 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 [http://poedit.net/] provides a very convenient cross-platform alternative.
 +
 
 +
=== Adding a new language ===
 +
 
 +
If you want to add a new language, copy the <code>agocontrol.pot</code> file to your language code. For example, to create a new (Hungarian) translation copy it to <code>hu.po</code>.
 +
 
 +
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 <code>#agocontrol-devel</code> on the <code>freenode.net</code>.
 +
 
 +
=== 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 [https://wiki.agocontrol.com/index.php/CompilingSource].
 +
 
 +
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 <code>-B</code> options tells <code>make</code> to build the target unconditionally. This is unfortunately needed, as <code>make</code> 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 <code>/opt/agocontrol</code>. So the (already translated) HTML files are stored at <code>/opt/agocontrol/html</code>. 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 <code>agorpc</code> component to your git checkout's build directory (for example <code>/home/user/agocontrol/build/core/rpc/html</code>) by changing the <code>htdocs</code> option in <code>/etc/opt/agocontrol/conf.d/rpc.conf</code>:
 +
 
 +
[rpc]
 +
# commented default location
 +
# htdocs=/opt/agocontrol/html
 +
htdocs=/home/user/agocontrol/build/core/rpc/html
 +
 
 +
Reload the <code>agorpc</code> component by issuing (as <code>root</code>):
 +
 
 +
systemctl restart agorpc
 +
 
 +
(Re)load the web page in your browser and check your translation. The interface files are now taken from this directory.

Latest revision as of 14:15, 6 March 2016

Contents

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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