Changes between Initial Version and Version 1 of OSGeoLive_Translation_Process


Ignore:
Timestamp:
20 Dec 2017 13:46:42 (23 months ago)
Author:
bakaniko
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • OSGeoLive_Translation_Process

    v1 v1  
     1__FORCETOC__
     2
     3= WORK IN PROGRESS =
     4
     5Documentation and tests are work in progress.
     6
     7This documentation might need adjustments to focus on the OSGeo Live Project.
     8
     9The list of [https://www.transifex.com/osgeo/osgeolive/content/ resources]
     10are classified as:
     11* ">>" Urgent  - OSGeo-Live related files
     12
     13[[File: OSGEo-Live_transifex_01_index.png | 500px ]]
     14
     15* "^"  High    - Projects related files
     16
     17[[File: OSGEo-Live_transifex_02_second_priority.png | 500px ]]
     18
     19* "-"  Normal  - Deprecated projects files (not for translating)
     20
     21[[File: OSGEo-Live_transifex_03_retired_files.png | 500px ]]
     22
     23You can easily order them by Version (v11) and and descending priority
     24
     25[[File : OSGEo-Live_transifex_04_priority.png | 500px ]]
     26
     27The list of [https://www.transifex.com/osgeo/osgeolive/languages/ Languages]
     28* Finnish
     29* French
     30* German
     31* Greek
     32* Japanese
     33* Polish
     34* Spanish
     35* Mexican spanish
     36
     37= The general process OSGeo-Live used for documentation: =
     38
     39<ul>
     40<li>The developer use [http://docutils.sourceforge.net/docs/user/rst/quickstart.html ReStructuredText] syntax to write the documentation in English.</li>
     41<li>That documentation is then used with [http://sphinx-doc.org/contents.html Sphinx] to generate the english html, man, pdf, etc.</li>
     42<li>Also using [http://sphinx-doc.org/latest/intl.html Sphinx-intl] the <code>*.pot</code> files are generated.</li>
     43<li>Those <code>*.pot</code> files are used by [https://www.transifex.com/osgeo/osgeolive Transifex] and they contain only the strings that need to be translated.</li>
     44<li>Translator works with those strings using the process bellow.</li>
     45<li>When the translator finishes a language, the git hub mantainers proceed to download the generated <code>*.po</code> files that contain the translated strings and commit them in git hub and update the documentation page.</li>
     46<li><p>Users can create their translation using:</p>
     47<p>tools/transifex/create_translation.sh fr</p></li></ul>
     48
     49Translations 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.
     50
     51= Before you start =
     52
     53== Prepare your clone for documentation ==
     54
     55<pre>
     56## Prepare the directory
     57git clone https://github.com/OSGeo/OSGeoLive-doc docClone
     58cd docClone
     59git checkout develop ## new things come into develop, then are merged into master
     60mkdir build
     61cd build
     62
     63## prepare the documentation for French (English is automatically build)
     64cmake -DHTML=ON -DFR=ON ..
     65## Build the doc
     66make doc
     67cd ..</pre>
     68
     69== Downloading translation ==
     70
     71* To download a particular file.
     72
     73Best when reviewing the file:
     74
     75<pre>
     76tx pull -l fr -r osgeolive.quickstart--ideditor_quickstart
     77</pre>
     78
     79* Download the latest translated <code>*.po</code> files of your language based on translation percentage.
     80
     81<pre>
     82tx pull -l fr --minimum-perc=100
     83</pre>
     84
     85
     86* Ask for help:
     87
     88<pre>
     89tx pull --help
     90</pre>
     91
     92=== Checking the download ===
     93
     94<pre>
     95git status
     96</pre>
     97
     98A possible output:
     99
     100== Have your language documentation html open. ==
     101
     102Viewing your language html will help to put strings in context and/or check the translation.
     103
     104<pre>tools/transifex/create_translations.sh fr</pre>
     105The French documentation would be in
     106
     107<pre>build/doc/html/fr/doc/index.html</pre>
     108
     109== Transifex files that are not accepting translations. ==
     110
     111Files 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.
     112
     113== English spelling and grammar ==
     114
     115Sometimes 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.
     116
     117= Working with small strings =
     118
     119== Choose the small files first. ==
     120
     121For &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.
     122
     123== Use &quot;translate&quot; button ==
     124
     125The &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.
     126
     127Don't use &quot;translate&quot; button on stand alone references like
     128
     129<pre>en:  :ref:`sample`
     130ja:  :ref:`サンプル`    &lt;--- wrong</pre>
     131== Use a &quot;suggestion&quot; ==
     132
     133When 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:
     134
     135<pre>en:              :ref:`pgr_astar&lt;pgr_astar&gt;` - Shortest Path A*
     136Use suggestion:   pgr_astar - A*アルゴリズムを用いた最短経路探索
     137Modify to:       :ref:`pgr_astar&lt;pgr_astar&gt;` - A*アルゴリズムを用いた最短経路探索</pre>
     138== Use &quot;copy button&quot; ==
     139
     140Copy the the stand alone references like
     141
     142<pre>en:  :ref:`sample`
     143ja:  :ref:`sample`</pre>
     144== Type a translation ==
     145
     146You can just type your translation.
     147
     148== Go to the next string ==
     149
     150When 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).
     151
     152== Save your translation ==
     153
     154Make sure all strings using the &quot;Save all unsaved translations&quot; button.
     155
     156= Check your work =
     157
     158This 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; .
     159
     160== Download the translated file and recreate the translation ==
     161
     162If the file you modified in transifex is doc--src--changelog--index and want to check the Japanese translation
     163
     164<pre>tools/transifex/download_translation.sh ja pgrouting.doc--src--changelog--index
     165tools/transifex/create_translations.sh ja</pre>
     166Navigate to the the translated file, for this example it would be
     167
     168<pre>build/doc/html/ja/doc/src/changelog/index.html</pre>
     169Notice the relation between names:
     170
     171<pre>Transifex name:              pgrouting.doc--src--changelog--index
     172Html Generated File: build/doc/html/ja/doc/src/changelog/index.html</pre>
     173And visualy compare the &quot;looks&quot; with the [English version] (http://docs.pgrouting.org/2.0/en/doc/index.html)
     174
     175== Use the &quot;Approve translation&quot; button ==
     176
     177When the file is fully translated (except the navigation bar), you can are about to approve the translation, '''????????'''
     178
     179* Check the links first, example: there is a link to sample data.
     180
     181Example:
     182
     183<pre>html:    上記クエリは サンプルデータ のネットワークを使用しています。   &lt;-- sample data is translated
     184or:      上記クエリは Sample Data のネットワークを使用しています。   &lt;--- sample data needs translation</pre>
     185If you can navigate the links, you are ok
     186
     187* When using create_translation script there was no &quot;inline&quot; error (see [[Translation Troubleshooting]] ), you are ok
     188
     189If you are ok, then choose a string and click the &quot;Approve translation&quot; button.
     190
     191= Which file is next =
     192
     193== Do doc--index last ==
     194
     195That way you can use the &quot;Use suggestion&quot; in this file.
     196
     197== Work &quot;important&quot; files first ==
     198
     199All 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.
     200
     201- your project files: you know that project certainly better than us, especially in your language; starting by the overview then the quickstart
     202- OSGeoLive files: there is several core files for the OSgeoLive documentation:
     203    - index
     204    - overview--overview
     205    - overview--toc
     206    - quickstart--virtualization_quickstart
     207    - quickstart--usb_quickstart
     208    - quickstart--osgeolive_quickstart
     209    - copyright
     210    - contributors
     211    - translators
     212    - presentation
     213    - sponsors
     214
     215etc
     216
     217They are listed with a red double ">" priority sign
     218
     219== Work the &quot;almost finished&quot; files ==
     220
     221After 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:
     222
     223* Click Documentation
     224* Click on your language
     225* click on the sorting button (sorts by % of termination)
     226
     227This is very useful when you have a lot of files already translated
     228
     229== Work files that belong to a directory ==
     230
     231Based on the following files:
     232
     233* doc--src--changelog--1_x ... 150 words (25 strings) ...
     234* doc--src--changelog--2_0 ... 277 words (26 strings) ...
     235* doc--src--changelog--index ... 4 words (3 strings) ...
     236
     237Maybe you started working with doc--src--changelog--index, so the next step would be to work with
     238
     239* doc--src--changelog--1_x
     240* doc--src--changelog--2_0
     241
     242So you finished a section, go [[Translation Check your work]].
     243
     244= Troubleshooting =
     245
     246Please post any question in [https://github.com/pgRouting/pgrouting/issues/200 issue 200]
     247
     248== The :ref:`nameoflink` link is not translated ==
     249
     250Example
     251
     252<pre>en:      The queries use the :ref:`sampledata` network.
     253ja:      上記クエリは :ref:`sampledata` のネットワークを使用しています。 
     254html:    上記クエリは Sample Data のネットワークを使用しています。</pre>
     255Thats 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.
     256
     257== The :ref:`nameoflink` link is the only thing that is translated ==
     258
     259Example
     260
     261<pre>en:      The queries use the :ref:`sampledata` network.
     262ja:      The queries use the :ref:`sampledata` network.
     263html:    The queries use the サンプルデータ  network.</pre>
     264Maybe you navigated into an untranslated page that has a reference to a translated page.
     265
     266== I don't see the link but I can read :ref: in the html page ==
     267
     268This is a common problem when using the translation button.<br />
     269Example
     270
     271<pre>en:      The queries use the :ref:`sampledata` network.
     272ja:      上記クエリは: ref:'sampledata'のネットワークを使用しています。   
     273html:    上記クエリは: ref:'sampledata'のネットワークを使用しています。</pre>
     274The 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:
     275
     276<pre>                            -------------------
     277en:      The queries use the :ref:`sampledata` network.
     278ja:      上記クエリは :ref:`sampledata` のネットワークを使用しています。   
     279html:    上記クエリは サンプルデータ のネットワークを使用しています。
     280  or:    上記クエリは Sample Data のネットワークを使用しています。</pre>
     281
     282== WARNING: Inline literal start-string without end-string. ==
     283
     284You 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.
     285
     286Inline 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:
     287
     288<pre>``int4`` id of the end point
     289``int4``型の始点ノードのID         &lt;--- this will generate the error
     290``int4 `` 型の始点ノードのID       &lt;--- this will also generate the error (a space is after the 4)
     291``int4`` 型の始点ノードのID        &lt;--- a space is (before as a new line and) after the inline literal</pre>
     292= Tools for the Reviewer =
     293
     294== tools/transifex/download_translation.sh ==
     295
     296Use to update the <code>*.po</code> files that are in your system with the latest translation stored in Transifex.<br />
     297Languages available:
     298
     299* es - Spanish
     300* fr - French
     301* ja - Japanese
     302* de - German
     303
     304tools/transifex/download_translation.sh [es|ja|fr|de] [pgrouting.&lt;filename&gt;]
     305
     306To download all language translations:
     307
     308<pre>tools/transifex/download_translation.sh</pre>
     309To download all the translations of a particular language:
     310
     311<pre>tools/transifex/download_translation.sh [es|ja|fr|de]</pre>
     312To download the translation of a specific file you need to state the language also
     313
     314<pre>tools/transifex/download_translation.sh [es|ja|fr|de] [pgrouting.&lt;filename&gt;]</pre>
     315
     316== tools/transifex/create_translations.sh ==
     317
     318Use to create: html, man, pdf documentation of the languages based on the <code>*.po</code> files stored in your system. Languages available:
     319
     320* es - Spanish
     321* fr - French
     322* ja - Japanese
     323* de - German
     324
     325To create the documentation of all the languages
     326
     327<pre>tools/transifex/create_translations.sh</pre>
     328To create the documentation of a particular language:
     329
     330<pre>tools/transifex/create_translations.sh [es|ja|fr|de]</pre>
     331The main index.html of the documentation will be located at:
     332
     333<pre>build/doc/html/[es|ja|fr|de]/doc/index.html</pre>
     334
     335= Main wiki page =
     336
     337* [https://wiki.osgeo.org/wiki/OSGeoLive OSGeoLive Wiki]
     338
     339
     340[[Category: OSGeoLive]]