Yii Documentation Project
This project aims 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
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 them online.
Thank you for your support and contribution to Yii!
Ensure UTF-8 encoding
---------------------
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.
protected/yiic 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.
protected/yiic 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.
protected/yiic 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.
Testing Translations
--------------------
You can use the included application 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
Translate Blockquote in the Guide and the Blog Tutorial
-------------------------------------------------------
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': ......
How to Synchronize the Guide and the Blog
-----------------------------------------
In order to keep track of the changes made to the source guide and blog pages,
for every translated page, we should append the source revision number
by copying the following line from the source page:
$Id: basics.application.txt 626 ... $
A source page is updated, it will have a different revision number,
and we can use this number to detect if the corresponding translation
is up-to-date or not. We can then use SVN's tool to compare two revisions,
find out the changes to the source page, and synchronize the translation
accordingly.
NOTE: we should not set "id" as SVN keyword for the translated pages.
Otherwise, the above revision reference will be automatically modified by SVN.
We have developed a command line tool to simplify the above task.
Under the yiidoc directory and in a command window, run the following command:
protected/yiic syncguide de
protected/yiic syncblog de
The command will check if translations in German are up-to-date.
How to Synchronize Messages
---------------------------
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
Directory Structure
-------------------
blog/ the blog tutorial
source/ the original blog text (read-only)
/ translation of the blog in a language
guide/ the definitive guide
source/ the original guide text (read-only)
/ translation of the guide in a language
messages/ the Yii core messages
/ translation of the messages in a language
views/
source/ the original system view files (read-only)
/ translation of the views in a language
requirements/
messages/ the messages for requirement checker
/ translation of the messages in a language
views/ the view files for requirement checker
source/ the original view files (read-only)
/ 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