Translation

Information for Translators

We use the Crowdin translation platform (see our project on Crowdin ) and their client to manage translations.

Usage

In command line mode, sending source files is done with this command:

crowdin-cli upload source

Downloading the existing translations is done with this command:

crowdin-cli download

Translating pages

You can directly edit any page (but don't forget to copy them on Crowdin after translating it) or you can use Crowdin's interface directly.

The second option is the easiest for most people.

Adding new pages

1. Create the page in English or at least create an issue to ask someone to do it for you
2. This page must have a name related to its content and should be named in the language you are translating into
3. In the source/LANGUAGE/index.rst file, create a link to your new page
4. In the crowdin.yaml file, create the information related to this new page now ready for translation
5. Push the new page to Crowdin

Adding a new language

1. Create the new directory under source/LANGUAGE, where LANGUAGE is the locale code for the new language you want to add (see this page for the list of supported languages and their locale code on Crowdin)
2. In the crowdin.yaml file add the new language for each translation (under languages_mapping)
3. Set the language in conf.py (see the language list)
4. Push your translation to Crowdin

Building the documentation

Usage

php builddoc

Or you can also use

./builddoc

Requirements

• Having sphinx installed
• Having php cli available
• Having crowdin-cli installed

Building using Docker

SPHINXBUILD="docker run --rm -v $PWD:/doc umbrellium/sphinx-doc sphinx-build" ./builddoc html

To clean the doc generated by docker use the following command

docker run --rm -v $PWD:/doc umbrellium/sphinx-doc rm -rf build/*

Check for lint errors in code examples

Install dependencies:

composer install

Run rusy to check for code examples:

./vendor/bin/rusty check --no-execute source/ -v

FAQ

Why Crowdin?

Crowdin helps seeing the progression of translations. It also has a good suggestion module created both from the already translated parts and from Bing Translator.

Do we need to translate anchors?

An anchor in the documentation is displayed as such:

.. _installation-par-composer:

They must not be translated and remain the same as in the original translation. It will be easier for other people to translate other page referencing this anchor. Translations anchors would result in broken links when you switch language on the site.

Where can I find the syntax for the files?

We use the reStructuredText syntax. You can find it on the sphinx website.

What are the title underline order?

In reStructuredText syntax, you can use a wide variety of character to underline. The order use in the atoum documentation is : #, *, =, -, ", ^, `, :, ., ' . Now if you have more than 4 subdivisions you may want to split your document into multiple files.

What's the licence of this documentation.

This documentation is under the CC by-nc-sa 4.0 licence. You can find more information on this page

I have a problem, where can I find help?

You can check our IRC channel ##atoum on freenode

What thing should not be translated

Some thing should not be translated

• anchor/ref
• directory name