Difference between revisions of "OSGeoLive Translation Process"

From OSGeo
Jump to navigation Jump to search
Line 50: Line 50:
 
Translations to French are going to be used as examples along this wiki, we choose French so you can focus on what is being translated and what is not.
 
Translations to French are going to be used as examples along this wiki, we choose French so you can focus on what is being translated and what is not.
  
= Before you start =
+
== Before you start ==
  
== Prepare your clone for documentation ==
+
=== Prepare your clone for documentation ===
  
 
<pre>
 
<pre>
Line 68: Line 68:
 
cd ..</pre>
 
cd ..</pre>
  
== Downloading translation ==
+
=== Downloading translation ===
  
 
* To download a particular file.
 
* To download a particular file.
Line 91: Line 91:
 
</pre>
 
</pre>
  
=== Checking the download ===
+
==== Checking the download ====
  
 
<pre>
 
<pre>
Line 99: Line 99:
 
A possible output:
 
A possible output:
  
== Have your language documentation html open. ==
+
=== Have your language documentation html open. ===
  
 
Viewing your language html will help to put strings in context and/or check the translation.
 
Viewing your language html will help to put strings in context and/or check the translation.
Line 108: Line 108:
 
<pre>build/doc/html/fr/doc/index.html</pre>
 
<pre>build/doc/html/fr/doc/index.html</pre>
  
== Transifex files that are not accepting translations. ==
+
=== Transifex files that are not accepting translations. ===
  
 
Files not accepting translations are marked with a red dot, maybe the file belongs to a previous version of OSGeo-Live documentation, or it was moved from one directory to another. Those files are not erased from the system so any translated string can be reused.
 
Files not accepting translations are marked with a red dot, maybe the file belongs to a previous version of OSGeo-Live documentation, or it was moved from one directory to another. Those files are not erased from the system so any translated string can be reused.
  
== English spelling and grammar ==
+
=== English spelling and grammar ===
  
 
Sometimes the developers and the reviewers have typos in the English version, you will see spelling typos with a wavy red line, unfortunately it is too late to correct them for the current version. So proceed with the translation with the best of your ability. For the grammar, if you don't understand what is being told, please go to [https://github.com/pgRouting/pgrouting/issues/200 issue 200] to post a comment stating the file and pasting the English string. If a change has been considered, the string to be translated will be posted on the &quot;instructions&quot; for the string.
 
Sometimes the developers and the reviewers have typos in the English version, you will see spelling typos with a wavy red line, unfortunately it is too late to correct them for the current version. So proceed with the translation with the best of your ability. For the grammar, if you don't understand what is being told, please go to [https://github.com/pgRouting/pgrouting/issues/200 issue 200] to post a comment stating the file and pasting the English string. If a change has been considered, the string to be translated will be posted on the &quot;instructions&quot; for the string.
  
= Working with small strings =
+
== Working with small strings ==
  
== Choose the small files first. ==
+
=== Choose the small files first. ===
  
 
For &quot;small&quot; I mean the ones that have very few strings to be translated. That will start building up a bank of translated strings that can be used in larger files. To detect a &quot;small&quot; file go to the list of [resources] (https://www.transifex.com/projects/p/pgrouting/resources/) and choose a file with few words or few strings.
 
For &quot;small&quot; I mean the ones that have very few strings to be translated. That will start building up a bank of translated strings that can be used in larger files. To detect a &quot;small&quot; file go to the list of [resources] (https://www.transifex.com/projects/p/pgrouting/resources/) and choose a file with few words or few strings.
  
== Use &quot;translate&quot; button ==
+
=== Use &quot;translate&quot; button ===
  
 
The &quot;translate button&quot; comes quite handy, you still have to check the translation, and there is an &quot;undo&quot; button if you think that its better for you to type the translation than to modify the machine's translation.
 
The &quot;translate button&quot; comes quite handy, you still have to check the translation, and there is an &quot;undo&quot; button if you think that its better for you to type the translation than to modify the machine's translation.
Line 130: Line 130:
 
<pre>en:  :ref:`sample`
 
<pre>en:  :ref:`sample`
 
ja:  :ref:`サンプル`    &lt;--- wrong</pre>
 
ja:  :ref:`サンプル`    &lt;--- wrong</pre>
== Use a &quot;suggestion&quot; ==
+
=== Use a &quot;suggestion&quot; ===
  
 
When you work with transifex it builds up a translated string bank and it will show one or more suggestions. If the suggestion is very close to what is needed, use it, and change the translation to the final translation of the string. Example:
 
When you work with transifex it builds up a translated string bank and it will show one or more suggestions. If the suggestion is very close to what is needed, use it, and change the translation to the final translation of the string. Example:
Line 137: Line 137:
 
Use suggestion:  pgr_astar - A*アルゴリズムを用いた最短経路探索
 
Use suggestion:  pgr_astar - A*アルゴリズムを用いた最短経路探索
 
Modify to:      :ref:`pgr_astar&lt;pgr_astar&gt;` - A*アルゴリズムを用いた最短経路探索</pre>
 
Modify to:      :ref:`pgr_astar&lt;pgr_astar&gt;` - A*アルゴリズムを用いた最短経路探索</pre>
== Use &quot;copy button&quot; ==
+
=== Use &quot;copy button&quot; ===
  
 
Copy the the stand alone references like
 
Copy the the stand alone references like
Line 143: Line 143:
 
<pre>en:  :ref:`sample`
 
<pre>en:  :ref:`sample`
 
ja:  :ref:`sample`</pre>
 
ja:  :ref:`sample`</pre>
== Type a translation ==
+
=== Type a translation ===
  
 
You can just type your translation.
 
You can just type your translation.
  
== Go to the next string ==
+
=== Go to the next string ===
  
 
When you finished translating the string press &quot;tab&quot;, that way it get's saved, if you click to a different string, maybe because the next string is already translated, then it won't be saved (green/white stripes).
 
When you finished translating the string press &quot;tab&quot;, that way it get's saved, if you click to a different string, maybe because the next string is already translated, then it won't be saved (green/white stripes).
  
== Save your translation ==
+
=== Save your translation ===
  
 
Make sure all strings using the &quot;Save all unsaved translations&quot; button.
 
Make sure all strings using the &quot;Save all unsaved translations&quot; button.
  
= Check your work =
+
== Check your work ==
  
 
This step is needed not to check the translation but to check that ReStructuredText in the translated strings is correct. Many things might be wrong, an extra space, a missing space or a missing character &quot;`&quot; .
 
This step is needed not to check the translation but to check that ReStructuredText in the translated strings is correct. Many things might be wrong, an extra space, a missing space or a missing character &quot;`&quot; .
  
== Download the translated file and recreate the translation ==
+
=== Download the translated file and recreate the translation ===
  
 
If the file you modified in transifex is doc--src--changelog--index and want to check the Japanese translation
 
If the file you modified in transifex is doc--src--changelog--index and want to check the Japanese translation
Line 174: Line 174:
 
And visualy compare the &quot;looks&quot; with the [English version] (http://docs.pgrouting.org/2.0/en/doc/index.html)
 
And visualy compare the &quot;looks&quot; with the [English version] (http://docs.pgrouting.org/2.0/en/doc/index.html)
  
== Use the &quot;Approve translation&quot; button ==
+
=== Use the &quot;Approve translation&quot; button ===
  
 
When the file is fully translated (except the navigation bar), you can are about to approve the translation, '''????????'''
 
When the file is fully translated (except the navigation bar), you can are about to approve the translation, '''????????'''
Line 190: Line 190:
 
If you are ok, then choose a string and click the &quot;Approve translation&quot; button.
 
If you are ok, then choose a string and click the &quot;Approve translation&quot; button.
  
= Which file is next =
+
== Which file is next ==
  
== Do doc--index last ==
+
=== Do doc--index last ===
  
 
That way you can use the &quot;Use suggestion&quot; in this file.
 
That way you can use the &quot;Use suggestion&quot; in this file.
  
== Work &quot;important&quot; files first ==
+
=== Work &quot;important&quot; files first ===
  
 
All files are important, but the following files are the core of the project. Most of them have repeated strings, so the &quot;Use Suggestion&quot; tactic is perfect, and you can use the search box to find them.
 
All files are important, but the following files are the core of the project. Most of them have repeated strings, so the &quot;Use Suggestion&quot; tactic is perfect, and you can use the search box to find them.
Line 218: Line 218:
 
They are listed with a red double ">" priority sign
 
They are listed with a red double ">" priority sign
  
== Work the &quot;almost finished&quot; files ==
+
=== Work the &quot;almost finished&quot; files ===
  
 
After you finish a file, you can choose a file that is &quot;almost done&quot;. I found pretty uncomfortable the list placed at the left, so to choose an almost done file I recommend:
 
After you finish a file, you can choose a file that is &quot;almost done&quot;. I found pretty uncomfortable the list placed at the left, so to choose an almost done file I recommend:
Line 228: Line 228:
 
This is very useful when you have a lot of files already translated
 
This is very useful when you have a lot of files already translated
  
== Work files that belong to a directory ==
+
=== Work files that belong to a directory ===
  
 
Based on the following files:
 
Based on the following files:
Line 247: Line 247:
 
Please post any question in [https://github.com/pgRouting/pgrouting/issues/200 issue 200]
 
Please post any question in [https://github.com/pgRouting/pgrouting/issues/200 issue 200]
  
== The :ref:`nameoflink` link is not translated ==
+
=== The :ref:`nameoflink` link is not translated ===
  
 
Example
 
Example
Line 256: Line 256:
 
Thats and indication that the referenced page for Sample Data, isn't fully translated. If you can click on the link and navigate you are ok.
 
Thats and indication that the referenced page for Sample Data, isn't fully translated. If you can click on the link and navigate you are ok.
  
== The :ref:`nameoflink` link is the only thing that is translated ==
+
=== The :ref:`nameoflink` link is the only thing that is translated ===
  
 
Example
 
Example
Line 265: Line 265:
 
Maybe you navigated into an untranslated page that has a reference to a translated page.
 
Maybe you navigated into an untranslated page that has a reference to a translated page.
  
== I don't see the link but I can read :ref: in the html page ==
+
=== I don't see the link but I can read :ref: in the html page ===
  
 
This is a common problem when using the translation button.<br />
 
This is a common problem when using the translation button.<br />
Line 281: Line 281:
 
   or:    上記クエリは Sample Data のネットワークを使用しています。</pre>
 
   or:    上記クエリは Sample Data のネットワークを使用しています。</pre>
  
== WARNING: Inline literal start-string without end-string. ==
+
=== WARNING: Inline literal start-string without end-string. ===
  
 
You will get this error is when using ''tools/transifex/create_translations.sh''. Languages like Japanese that don't use spaces to separate words are more likely to have this error. Unfortunately the error is shown only in line 1.
 
You will get this error is when using ''tools/transifex/create_translations.sh''. Languages like Japanese that don't use spaces to separate words are more likely to have this error. Unfortunately the error is shown only in line 1.
Line 293: Line 293:
 
= Tools for the Reviewer =
 
= Tools for the Reviewer =
  
== tools/transifex/download_translation.sh ==
+
=== tools/transifex/download_translation.sh ===
  
 
Use to update the <code>*.po</code> files that are in your system with the latest translation stored in Transifex.<br />
 
Use to update the <code>*.po</code> files that are in your system with the latest translation stored in Transifex.<br />
Line 315: Line 315:
 
<pre>tools/transifex/download_translation.sh [es|ja|fr|de] [pgrouting.&lt;filename&gt;]</pre>
 
<pre>tools/transifex/download_translation.sh [es|ja|fr|de] [pgrouting.&lt;filename&gt;]</pre>
  
== tools/transifex/create_translations.sh ==
+
=== tools/transifex/create_translations.sh ===
  
 
Use to create: html, man, pdf documentation of the languages based on the <code>*.po</code> files stored in your system. Languages available:
 
Use to create: html, man, pdf documentation of the languages based on the <code>*.po</code> files stored in your system. Languages available:

Revision as of 13:07, 26 February 2018


Translate on Transifex

Documentation and tests are work in progress.

This documentation might need adjustments to focus on the OSGeo Live Project.

The list of resources are classified as:

  • ">>" Urgent - OSGeo-Live related files

OSGEo-Live transifex 01 index.png

  • "^" High - Projects related files

OSGEo-Live transifex 02 second priority.png

  • "-" Normal - Deprecated projects files (not for translating)

OSGEo-Live transifex 03 retired files.png

You can easily order them by Version (v11) and and descending priority

OSGEo-Live transifex 04 priority.png

The list of Languages

  • Finnish
  • French
  • German
  • Greek
  • Japanese
  • Polish
  • Spanish
  • Mexican spanish

Build the documentation

The general process OSGeo-Live used for documentation:

  • The developer use ReStructuredText syntax to write the documentation in English.
  • That documentation is then used with Sphinx to generate the english html, man, pdf, etc.
  • Also using Sphinx-intl the *.pot files are generated.
  • Those *.pot files are used by Transifex and they contain only the strings that need to be translated.
  • Translator works with those strings using the process bellow.
  • When the translator finishes a language, the git hub mantainers proceed to download the generated *.po files that contain the translated strings and commit them in git hub and update the documentation page.
  • Users can create their translation using:

    tools/transifex/create_translation.sh fr

Translations to French are going to be used as examples along this wiki, we choose French so you can focus on what is being translated and what is not.

Before you start

Prepare your clone for documentation

## Prepare the directory
git clone https://github.com/OSGeo/OSGeoLive-doc docClone
cd docClone
git checkout develop ## new things come into develop, then are merged into master
mkdir build
cd build

## prepare the documentation for French (English is automatically build)
cmake -DHTML=ON -DFR=ON .. 
## Build the doc
make doc
cd ..

Downloading translation

  • To download a particular file.

Best when reviewing the file:

tx pull -l fr -r osgeolive.quickstart--ideditor_quickstart
  • Download the latest translated *.po files of your language based on translation percentage.
tx pull -l fr --minimum-perc=100


  • Ask for help:
tx pull --help

Checking the download

git status

A possible output:

Have your language documentation html open.

Viewing your language html will help to put strings in context and/or check the translation.

tools/transifex/create_translations.sh fr

The French documentation would be in

build/doc/html/fr/doc/index.html

Transifex files that are not accepting translations.

Files not accepting translations are marked with a red dot, maybe the file belongs to a previous version of OSGeo-Live documentation, or it was moved from one directory to another. Those files are not erased from the system so any translated string can be reused.

English spelling and grammar

Sometimes the developers and the reviewers have typos in the English version, you will see spelling typos with a wavy red line, unfortunately it is too late to correct them for the current version. So proceed with the translation with the best of your ability. For the grammar, if you don't understand what is being told, please go to issue 200 to post a comment stating the file and pasting the English string. If a change has been considered, the string to be translated will be posted on the "instructions" for the string.

Working with small strings

Choose the small files first.

For "small" I mean the ones that have very few strings to be translated. That will start building up a bank of translated strings that can be used in larger files. To detect a "small" file go to the list of [resources] (https://www.transifex.com/projects/p/pgrouting/resources/) and choose a file with few words or few strings.

Use "translate" button

The "translate button" comes quite handy, you still have to check the translation, and there is an "undo" button if you think that its better for you to type the translation than to modify the machine's translation.

Don't use "translate" button on stand alone references like

en:  :ref:`sample`
ja:  :ref:`サンプル`    <--- wrong

Use a "suggestion"

When you work with transifex it builds up a translated string bank and it will show one or more suggestions. If the suggestion is very close to what is needed, use it, and change the translation to the final translation of the string. Example:

en:              :ref:`pgr_astar<pgr_astar>` - Shortest Path A*
Use suggestion:   pgr_astar - A*アルゴリズムを用いた最短経路探索
Modify to:       :ref:`pgr_astar<pgr_astar>` - A*アルゴリズムを用いた最短経路探索

Use "copy button"

Copy the the stand alone references like

en:  :ref:`sample`
ja:  :ref:`sample`

Type a translation

You can just type your translation.

Go to the next string

When you finished translating the string press "tab", that way it get's saved, if you click to a different string, maybe because the next string is already translated, then it won't be saved (green/white stripes).

Save your translation

Make sure all strings using the "Save all unsaved translations" button.

Check your work

This step is needed not to check the translation but to check that ReStructuredText in the translated strings is correct. Many things might be wrong, an extra space, a missing space or a missing character "`" .

Download the translated file and recreate the translation

If the file you modified in transifex is doc--src--changelog--index and want to check the Japanese translation

tools/transifex/download_translation.sh ja pgrouting.doc--src--changelog--index
tools/transifex/create_translations.sh ja

Navigate to the the translated file, for this example it would be

build/doc/html/ja/doc/src/changelog/index.html

Notice the relation between names:

Transifex name:              pgrouting.doc--src--changelog--index
Html Generated File: build/doc/html/ja/doc/src/changelog/index.html

And visualy compare the "looks" with the [English version] (http://docs.pgrouting.org/2.0/en/doc/index.html)

Use the "Approve translation" button

When the file is fully translated (except the navigation bar), you can are about to approve the translation, ????????

  • Check the links first, example: there is a link to sample data.

Example:

html:    上記クエリは サンプルデータ のネットワークを使用しています。   <-- sample data is translated
or:      上記クエリは Sample Data のネットワークを使用しています。   <--- sample data needs translation

If you can navigate the links, you are ok

If you are ok, then choose a string and click the "Approve translation" button.

Which file is next

Do doc--index last

That way you can use the "Use suggestion" in this file.

Work "important" files first

All files are important, but the following files are the core of the project. Most of them have repeated strings, so the "Use Suggestion" tactic is perfect, and you can use the search box to find them.

- your project files: you know that project certainly better than us, especially in your language; starting by the overview then the quickstart - OSGeoLive files: there is several core files for the OSgeoLive documentation:

   - index
   - overview--overview
   - overview--toc
   - quickstart--virtualization_quickstart
   - quickstart--usb_quickstart
   - quickstart--osgeolive_quickstart
   - copyright
   - contributors
   - translators
   - presentation
   - sponsors

etc

They are listed with a red double ">" priority sign

Work the "almost finished" files

After you finish a file, you can choose a file that is "almost done". I found pretty uncomfortable the list placed at the left, so to choose an almost done file I recommend:

  • Click Documentation
  • Click on your language
  • click on the sorting button (sorts by % of termination)

This is very useful when you have a lot of files already translated

Work files that belong to a directory

Based on the following files:

  • doc--src--changelog--1_x ... 150 words (25 strings) ...
  • doc--src--changelog--2_0 ... 277 words (26 strings) ...
  • doc--src--changelog--index ... 4 words (3 strings) ...

Maybe you started working with doc--src--changelog--index, so the next step would be to work with

  • doc--src--changelog--1_x
  • doc--src--changelog--2_0

So you finished a section, go Translation Check your work.

Troubleshooting

Please post any question in issue 200

The :ref:`nameoflink` link is not translated

Example

en:      The queries use the :ref:`sampledata` network.
ja:      上記クエリは :ref:`sampledata` のネットワークを使用しています。  
html:    上記クエリは Sample Data のネットワークを使用しています。

Thats and indication that the referenced page for Sample Data, isn't fully translated. If you can click on the link and navigate you are ok.

The :ref:`nameoflink` link is the only thing that is translated

Example

en:      The queries use the :ref:`sampledata` network.
ja:      The queries use the :ref:`sampledata` network.
html:    The queries use the サンプルデータ  network.

Maybe you navigated into an untranslated page that has a reference to a translated page.

I don't see the link but I can read :ref: in the html page

This is a common problem when using the translation button.
Example

en:      The queries use the :ref:`sampledata` network.
ja:      上記クエリは: ref:'sampledata'のネットワークを使用しています。   
html:    上記クエリは: ref:'sampledata'のネットワークを使用しています。

The link's generated by the button need to be corrected, I suggest to copy the link together with its sorrounding spaces from the English version:

                            -------------------
en:      The queries use the :ref:`sampledata` network.
ja:      上記クエリは :ref:`sampledata` のネットワークを使用しています。   
html:    上記クエリは サンプルデータ のネットワークを使用しています。
  or:    上記クエリは Sample Data のネットワークを使用しています。

WARNING: Inline literal start-string without end-string.

You will get this error is when using tools/transifex/create_translations.sh. Languages like Japanese that don't use spaces to separate words are more likely to have this error. Unfortunately the error is shown only in line 1.

Inline literals [specs] (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup) require a space before and after. The inline literals we use the most are of the type ``inlineliteral`` like in:

``int4`` id of the end point
``int4``型の始点ノードのID         <--- this will generate the error
``int4 `` 型の始点ノードのID       <--- this will also generate the error (a space is after the 4)
``int4`` 型の始点ノードのID        <--- a space is (before as a new line and) after the inline literal

Tools for the Reviewer

tools/transifex/download_translation.sh

Use to update the *.po files that are in your system with the latest translation stored in Transifex.
Languages available:

  • es - Spanish
  • fr - French
  • ja - Japanese
  • de - German

tools/transifex/download_translation.sh [es|ja|fr|de] [pgrouting.<filename>]

To download all language translations:

tools/transifex/download_translation.sh

To download all the translations of a particular language:

tools/transifex/download_translation.sh [es|ja|fr|de]

To download the translation of a specific file you need to state the language also

tools/transifex/download_translation.sh [es|ja|fr|de] [pgrouting.<filename>]

tools/transifex/create_translations.sh

Use to create: html, man, pdf documentation of the languages based on the *.po files stored in your system. Languages available:

  • es - Spanish
  • fr - French
  • ja - Japanese
  • de - German

To create the documentation of all the languages

tools/transifex/create_translations.sh

To create the documentation of a particular language:

tools/transifex/create_translations.sh [es|ja|fr|de]

The main index.html of the documentation will be located at:

build/doc/html/[es|ja|fr|de]/doc/index.html

Main wiki page