Version 10 (modified by 27 hours ago) ( diff ) | ,
---|
This document is deprecated. OSGeoLive stopped using Transifex Please go to Translations
This document is divided in two part, if you want to help us translate the OSGeoLive documentation, the first part will guide you through the Transifex platform. If you want to help us build it the second part will give you more technical information about Transifex, sphinx and the building process.
Translate on Transifex
Thanks for helping us translate the OSGeoLive project documentation !
You can find us there: https://www.transifex.com/osgeo/osgeolive/
Available languages
As for now (august 2022), there is 36 registered languages for the project. If your language is not in the list below (or on the updated list on Transifex), please make a request to add it !
The list of Languages:
- Hungarian (hu)
- Italian (it)
- Spanish (es)
- Spanish (Argentina)
- Spanish (Latin America)
- Spanish (Mexico)
- Spanish (Spain)
- Japanese (ja)
- German (de)
- French (fr)
- Finnish (fi)
- Swedish (sv)
- Turkish (Turkey)
- Portuguese (Brazil)
- Portuguese (Portugal)
- Dutch (nl)
- Chinese (zh)
- Chinese (China)
- Chinese (Taiwan)
- Polish (pl)
- Russian (ru)
- Swahili (sw)
- Estonian (et)
- Albanian (sq)
- Albanian (Albania)
- Arabic (Egypt)
- Bengali (bn)
- Bulgarian (bg)
- Catalan (ca)
- English (Albania)
- Greek (el)
- Hindi (hi)
- Korean (ko)
- Portuguese (pt)
- Romanian (ro)
- Urdu (ur)
Connect to the Transifex platform
If you don't have an account, please create one and then go to the project page.
Look for the language you want to help with (or ask to add it if it is not there already).
For each languages, there is a list of resources, it is the files to translate (actually 143 of them).
Files to translate
The list of resources are classified as:
- ">>" Urgent - OSGeo-Live related files
- "^" High - Projects related files
- "-" Normal - Deprecated projects files (not for translating)
Please note that the urgent files are the OSGeoLive project files, if you are more comfortable translating only the files of a project provided by OSGeoLive, it is perfectly ok. :)
Please note each project has 2 files:
- an overview prefixed with overview--<name of the project>
- a quickstart prefixed with quickstart--<name of the project>
Translation
Once you have choose a file to translate, a little summary appears:
- The choosen resource and the language, here overview--overview (French)
- Word count
- String count
- Translation button
After clicking on the translation button, you access to the translation panels:
- String counts: Total, non translated, non revised
- Reviewed string
- Translated non reviewed string
- raw string (in English)
- Raw string to be translated
- Translation panel
- Translation save button
- Review button (if you are a reviewer)
- Suggestions panel (from past translations, by similarity)
By clicking on a string in the left panel, it will be placed in the panel 5 and if possible a translation will be proposed in 6. You can edit this translation right from the panel 6 then save it by clicking on 7.
You are an OSGeoLive translator ! Congratulations !
Thanks for helping us. Now, you can translate another string then another, etc. And then another file :)
Welcome aboard !
Tips and tricks
Placeholders
Several strings are placeholders that will be replaced by internal links during the documentation build process.
Those strings start and end with a |
:
There is no need to translate them. Please copy from source.
To do it you can copy from source using the button provided:
If there is several of them you can select them then apply the copy from source function.
Links
Since the documentation is build using Sphinx and RST files, the RST syntax needs to be preserved when translating.
highlighting
Some words are emphasized in italic or bold font.
Please translate those words with respect to the emphasis.
For example this paragraph present both italic (on set of *) and bold (2 sets of *) words:
To reopen the *Monitor Test Run* view after it has been closed, select in the menu bar the **Status** section. The **Status** section shows all running tests. A click on the Test Run opens the *Monitor Test Run* view of that Test Run.
In French, it will be like this:
Pour rouvrir la vue *Monitor Test Run* après sa fermeture, sélectionnez dans la barre de menu la section **Statut**. La section **Statut** affiche tous les tests en cours d’exécution. Un clic sur la série de tests ouvre la vue *Monitor Test Run* de cette série de tests.
Internal links
The internal link syntax is like that:
:doc:`link caption <../path/to/file>`
Please translate the link caption but preserve the rest of the link. For example this link:
:doc:`Quickstart documentation <../quickstart/ETF_quickstart>`
can be translated in French like this:
:doc:`Guide de démarrage rapide <../quickstart/ETF_quickstart>`
External links
You can meet links related to documents outside the documentation. The syntax is like this:
`link caption <link>`__
For example, you can find them in sentences like this:
WMS services: a list of services is available `here <https://github.com/etf-validator/OSGeoLive-ETF/tree/main/resources/WMS-services>`__.
The French translation wil be like this:
Services WMS: une liste de service est disponible `ici <https://github.com/etf-validator/OSGeoLive-ETF/tree/main/resources/WMS-services>`__.
Roles
There is several roles where you can help us.
Translator
This role can translate strings, it is the most important job !
Reviewer
If your a confident enough in your language and technical knowledge, you can become a reviewer and review strings to fix the possible typos.
Language coordinator
A coordinator can accept new Translator and grant Reviewer privileges. With a lot of different languages, it helps a lot the administrator.
Build the documentation
The general process OSGeo-Live used for documentation:
This section is a work in progress, please excuse us.
<ul>
<li>The developer use ReStructuredText syntax to write the documentation in English.</li>
<li>That documentation is then used with Sphinx to generate the english html, man, pdf, etc.</li>
<li>Also using Sphinx-intl the *.pot
files are generated.</li>
<li>Those *.pot
files are used by Transifex and they contain only the strings that need to be translated.</li>
<li>Translator works with those strings using the process bellow.</li>
<li>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.</li>
<li><p>Users can create their translation using:</p>
<p>tools/transifex/create_translation.sh fr</p></li></ul>
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
- When using create_translation script there was no "inline" error (see Translation Troubleshooting ), 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.<br /> 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.<br />
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
Attachments (11)
- Language_resources.png (73.2 KB ) - added by 2 years ago.
- OSGEo-Live_transifex_01_index.png (6.3 KB ) - added by 2 years ago.
- OSGEo-Live_transifex_02_second_priority.png (7.1 KB ) - added by 2 years ago.
- OSGEo-Live_transifex_04_priority.png (28.8 KB ) - added by 2 years ago.
- OsgeoLive_translation_choosen_file.png (86.1 KB ) - added by 2 years ago.
- OsgeoLive_translation_translatefile.png (120.4 KB ) - added by 2 years ago.
- OSGEo-Live_transifex_03_retired_files.png (6.8 KB ) - added by 2 years ago.
- placeholders.png (2.9 KB ) - added by 2 years ago.
- placeholders_copy_from_source.png (14.0 KB ) - added by 2 years ago.
- placeholders_copy_from_source2.png (7.6 KB ) - added by 2 years ago.
- transifex_copy_from_source.png (8.1 KB ) - added by 2 years ago.
Download all attachments as: .zip