GitPHP uses Gettext for string tokenization. Gettext is a standard translation system for software. Going into all the details of how gettext translation works is beyond the scope of this document - this is just a high-level overview of the steps you need to take to see GitPHP in your language.
- Create a directory in the locale/ directory, named by your locale. (I’ll use en_US as my example throughout - so I’d create directory locale/en_US)
- locale/gitphp.pot contains all the extracted strings from the project, plus various translation comments I’ve added. This file is provided by me and updated anytime new strings are added. To get started, use this file to initialize a new po file in your locale directory:
msginit --locale=en_US -i locale/gitphp.pot -o locale/en_US/gitphp.po
- Translate all of the strings in this file. The easiest way to do this is by using a po editor. There are quite a few out there - poEdit is a popular one.
- If you’re doing this by hand, you will want to make sure all the headers at the top (Last-Translator, Plural-Forms, etc) are filled out correctly, and for each string, read the English in “msgid” and put the translated string into “msgstr”.
- Plural forms which have a “msgid” as well as a “msgid_plural” should have the singular translated string in
msgstr and the plural translated string in
- Parameters that are passed into the string - for example, dynamic counts or info from the page itself - appear as
%[num] with an option
$[type] behind it, for example %1 or %2$d. These should stay intact in your string, and the parameters will be inserted at runtime.
- You can look at any of the other existing locales as an example.
- One special string is ‘English’. I’ve made a note for the string, but don’t just translate ‘English’ into your language. This is the name of YOUR language - it’s displayed as the name of your language in the language picker. You want the name of your language, in your native language, so speakers of your language will recognize it without knowing English. For example, in the French locale, this would be “Français”, which is “French” IN French.
- Once you’re done, save and compile the po into a binary mo. This should be in the same directory as your po file. So for example, I would compile locale/en_US/gitphp.po into locale/en_US/gitphp.mo. Most po editors will do this for you - if not, you can compile it on the command line with the msgfmt command:
msgfmt -o locale/en_US/gitphp.mo locale/en_US/gitphp.po
- Every now and then, as the project’s code changes, new strings will come out or strings will be modified, and your translation will be updated. In this case, you will need to merge the updates from locale/gitphp.pot into your translation. You can run this command to see what updates are needed (the order of parameters is important here):
msgmerge locale/en_US/gitphp.po locale/gitphp.pot
Add the -U flag to do the actual update in your file. All your existing translations will be left alone, and new strings will be added for you to translate. A string that was translated already but may have been changed slightly will be marked “fuzzy” - this means you should evaluate whether the existing translation is still correct for the changed string. If it’s ok as-is, just mark it as not fuzzy. If it needs to be updated, update it. After all your updates are done, save and make sure to recompile your mo file.
That’s all for translation. As long as your mo file is compiled, it will be available as a language choice. If you submit your translation po to me, I can include it with the official distribution and everyone can benefit from it.