Xataface stores its translations in INI files in its lang directory, one for each language. You can develop your own translation by first copying the en.ini file to xx.ini (where xx is the ISO language code for the language you are translating for), then modifying the translations into your target language. NOTE: THIS IS NOT THE PREFERRED WAY TO CONTRIBUTE TRANSLATIONS. PLEASE SEE "Adding Translations Using Google Spreadsheets" BELOW.
Anatomy of a Language .INI file
The language .INI files (e.g. en.ini, es.ini, etc...) consist of key-value pairs, where the key is a unique identifier for a string in Xataface, and the value is the translation. All language files should contain the same keys, however if you omit a key from your translation, Xataface will just fall back to the default value that is defined in the PHP source code.
Example Snippet from en.ini file
scripts.GLOBAL.FORMS.OPTION_PLEASE_SELECT = "Please Select ..."
save_button_label = "Save"
scripts.GLOBAL.MESSAGE.PERMISSION_DENIED = "Permission Denied"
scripts.GLOBAL.NO_RECORDS_MATCHED_REQUEST = "No records matched your request."
In this small segment you can see 4 strings that are translated. The values on the left of the equals sign are the keys. Their corresponding values are on the right of the equals signs. A corresponding segment of the fr.ini (French) language file looks like:
You can see that the keys (the values on the left) are identical to those in the en.ini snippet. Only the values are changed (translated) into French.
NOTE: IT IS BETTER TO USE GOOGLE SPREADSHEETS TO EDIT TRANSLATIONS, THAN TO WORK WITH INI FILES DIRECTLY. PLEASE SEE "Adding Translations Using Google Spreadsheets" BELOW
Gotchas: Things to watch out for
When editing or adding translations in INI files, you need to be aware of a few gotchas related to how INI files work. If you mess up a line by forgetting to add a quote, you could cause a parse error which would cause Xataface to ignore the language file altogether. The following are a few common pitfalls:
Use UTF-8 Encoding
All ini files should use UTF-8 encoding, so make sure you are using a text editor that supports UTF-8 if you want to edit INI files. (But it is better to just use Google Spreadsheets for the editing if possible, in which case you don't have to worry about this).
Wrap Translations in Double Quotes
All translations should be wrapped in double quotes. E.g.
If you forget to close a quote, it will likely cause a parse error and Xataface will fail to load the file. E.g.
would be a problem.
Can't Use Double Quotes as Part of the Translation
Since INI files use double quotes to wrap strings, you can't use a double quote inside your translation. E.g. you can't do this:
because of the inline double quotes.
One way around this is to try to use single quotes where possible. E.g.
Another way around this is to the "_Q" key sequence, which Xataface will automatically convert to a double quote for you at runtime. E.g. You could do:
NOTE: If you use Google Spreadsheets to edit your translations, you won't have this problem. You can use double quotes inside your translations. The csv2ini? tool will automatically convert these to an appropriate form when the spreadsheet is converted to the INI files.
Leave Variables Alone
Some translated strings include variables that are meant to be replaced by Xataface at runtime. These should be left intact across translations. You can identify a variable by their resemblance to PHP variables (prefixed with a $).
E.g. In the en.ini file, the translation:
No action found = "No action found named '$name'"
has the variable $name.
So the French translation should maintain this variable. E.g. in the fr.ini file:
No action found = "Aucune action nommée '$name'"
Adding Translations Using Google Spreadsheets
In order to help keep translations more up to date, we have developed a set of tools to enable us to use Google Spreadsheets to edit and add translations, and convert these spreadsheets on demand into an appropriate set of language INI files.
The spreadsheet containing the Xataface translations is public to view and is located here. If you would like to add your own translations or modify existing translations, please contact Steve Hannah so that you can be given editor permission. You will first need a google docs account, then we can give you permission to edit the spreadsheet.
This centralized spreadsheet is converted to INI files and merged into SVN before every release. You can also export this spreadsheet as a CSV and convert it to Xataface's language INI files yourself using the csv2ini? tool that is located in the tools directory of the Xataface distribution.
Gotchas with Google Spreadsheets
Editing translations with Google Spreadsheets is much safer than editing the INI files directly. You don't have to worry about encoding issues, and you don't have to dance around double quotes like you do with INI files. There is only one known thing to watch out for:
Starting a translation with a Single Quote
If you start a translation with a single quote, Google Spreadsheets will interpret this as a directive to indicate that the contents of that cell should be considered a string (and not a number for example). E.g. If you enter the following into a Google Spreadsheets cell:
'Help!', I exclaimed
If you unfocus from that cell it will only say:
Help!', I exclaimed
If you go back into edit mode of the cell again, you'll see your opening single quote again... and when you tab out, it will disappear again.
You can work around this issue by just using two single-quotes for the first quote. E.g.:
''Help!', I exclaimed
This way Google will interpret the first quote as a directive, and it will use the second one as an actual single quote.
Converting the Google Translation Spreadsheet into INI Files
So you've contributed a number of translations to the Xataface Translations Google Spreadsheet, and you want to be able to use them in your installation of Xataface before the next release. Just follow the steps below:
Download the spreadsheet as a CSV file, using the File > Download as > CSV (Current Sheet) menu item in Google Spreadsheets.
Run the csv2ini? PHP script located in the xataface/tools directory to convert the xataface-translations.csv file that you downloaded from Google Spreadsheets in the previous step into INI files. The conversion command looks like:
This will convert the xataface-translations.csv file into a set of language INI files and place them the specified destination directory (don't forget the trailing slash) on /destination/dir so that the script knows its a directory. You can then copy these INI files into your xataface/lang directory to make them live.
Note: the csv2ini? script has only been used in a unix/os x type environment. Some small modifications would probably be necessary to make them work on Windows.