-
Notifications
You must be signed in to change notification settings - Fork 0
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 (currenlty it's still in yiidoc project) to test your translations online.
To access the application, the whole checked out folder should be placed
under a Web-accessible folder. For example, yiidoc.
And you can then access the Guide via:
http://hostname/path/to/yiidoc/index.php?r=guide
or the Blog tutorial via:
http://hostname/path/to/yiidoc/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 gudie 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
source/ the original blog text (read-only)
<lang>/ translation of the blog in a language
guide/ the definitive guide
source/ the original guide text (read-only)
<lang>/ translation of the guide in a language
messages/ the Yii core messages
<lang>/ translation of the messages in a language
views/
source/ the original system view files (read-only)
<lang>/ translation of the views in a language
requirements/
messages/ the messages for requirement checker
<lang>/ translation of the messages in a language
views/ the view files for requirement checker
source/ the original view files (read-only)
<lang>/ translation of the views in a language
framework/ the Yii framework directory (read-only)
The following directories and folders are for the included Web application. Do not translate them.
css/
protected/
index.php