-
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Documentation translation guidelines
The goal of translation project is to translate Yii core messages, system views and various documentation into different languages.
The directory structure is shown at the end of this file, where
<lang> stands for the language code for a particular language
(e.g. 'de' for German, 'zh_cn' for simplified Chinese).
File is the basic unit of translations. For each file to be
translated, you should create a new file with the same name and
save it under an appropriate directory. For example, in order to
translate the database.ar.txt file of the definitive guide into
German, you should save the translated file as guide/de/database.ar.txt.
MAKE SURE YOU USE UTF-8 ENCODING WHEN SAVING YOUR TRANSLATION.
Check in frequently instead of waiting till you finish all translations. As there may be several people translating in the same language, checking in frequently may help reduce duplicated work. It also gives other people chance to review your translation ealier.
If you participated in translating the Guide or the Blog tutorial,
you may leave your name in the index.txt page,
saying "translated by Your Name".
We will include the latest translations into every release of Yii, and also display finished ones online.
Thank you for your support and contribution to Yii!
It's very important that the translations are saved with a correct UTF-8 encoding. Especially wrongly encoded view files can cause massive trouble to developers and end-users (ie "headers already sent" error).
There's a special console command that will help you to ensure that your translations are correctly encoded.
This command will list every translation file which appears to have an incorrect UTF-8 encoding.
build utf8 checkencoding
If one of your translations is in there, please open it and save it with UTF-8 encoding. You may try Google or ask in the Forum on how to configure your editor so that the correct encoding gets applied.
This command will list every translation file which contains a so called UTF-8 BOM header.
build utf8 checkbom
Simply check if one of your translations is in there. If that's the case you can use the following command to remove the UTF-8 BOM header.
build utf8 fixbom /path/to/translation/file
When you're done with your files, simply re-run utf8 checkbom one more time to verify all
of your affected translations are indeed fixed.
You can use the included application to test your translations online.
To access the application, point your webserver root to docs directory.
Then you can then access the Guide via:
http://hostname/index.php?r=guide
or the Blog tutorial via:
http://hostname/index.php?r=blog
The Guide and the Blog contains blockquotes that start with tokens like "> Note:", "> Tip: ", and so on. Do not translate these tokens. Instead, append the translation of the token word and use "|" as the separator. For example,
> Note|translation for 'note': ....
> Tip|translation for 'tip': ......
In order to check if your translation is up to date and get info about what should be updated you should run the following commands (example is for Russian translation):
build translations report --sourcePath="../docs/guide" --translationPath="../docs/guide/ru" --title="Russian guide translation report" > report_guide_ru.html
build translations report --sourcePath="../docs/blog" --translationPath="../docs/blog/ru" --title="Russian blog translation report" > report_blog_ru.html
build translations report --sourcePath="../framework/views" --translationPath="../framework/views/ru" --title="Russian framework views translation report" > report_views_ru.html
After running it you'll have three reports full of useful info. Don't push these reports into your repository.
Make sure git is installed and is added to PATH environment variable
We have a tool to help synchronize changes made to Yii core messages and requirement checker messages. Check out an SVN copy of Yii framework. On command line under the "build" directory, run the following command:
build message ../framework/messages/config.php
This will extract original messages from Yii framework and merge them with the translations under the "messages" directory. You can now check the merged file to see if there is any change since you translate the messages last time. Similar procedure applies to the requirement checker messages, which can be synchronized using the following command:
build message ../requirements/messages/config.php
blog/ the blog tutorial (English)
<lang>/ translation of the blog into <lang> language
guide/ the definitive guide (English)
<lang>/ translation of the guide into <lang> language
The following directories and folders are for the doc viewer Web application. Do not translate them.
css/
viewer/
index.php