Somehow translating something from language into another by software and some kind of translation database is a trivial thing. This is the reason why there are countless translation frameworks out there.
Almost all of them have at least one of two common problems:
Qgoda's internationalization (i18n) is based on GNU gettext. GNU gettext is the de-facto standard for translating free and open-source software, and it really shines by its set of mature tools that automate the task of translation management to the extent possible.
If you want to dig deeper into the topic or if something is unclear, you can
always consult the GNU gettext documentation
big picture. This page covers mostly the qgoda-specific topics
only. But it should be enough to get you started.
Since Qgoda's internationalization is based on
GNU gettext you have to install
it first. GNU gettext is available for every platform, including Microsoft
Windows. But it is often split up into two packages
gettext-tools. Make sure that you install
gettext-tools which contains
the necessary tools.
You also need git. Git is available on all platforms.
linguas: - en - de - fr po: textdomain: com.your-site.www
The order of languages (line 1) matters! The first one is the default language
of your site. If you want to follow the examples on this page, make sure that
linguas contains at least two languages, one for your default language and
at least one that can contribute translations.
The textdomain is not really important. You can pretty much pick any identifier you want.
Most tasks are done with the sub-command
qgoda po. Try
qgoda po --help
for a reference.
Please note that you have to run the command
qgoda po from the top-level
directory of your site! Failure to do so will usually result in an error
configuration variable “po.textdomain” not set (because Qgoda cannot
find your configuration).
The translation workflow consists of several steps. You can perform the
steps individually (that is described below) or you all at once with the
qgoda po all, which will do all necessary steps at once. This
will usually result in some unnecessary actions but is easier to remember
Nevertheless, you should go at least once over the rest of the page so that you understand what is going on and how to translate things.
qgoda po all will fail until you have created your
first translation file! See
Adding a Language below how to do this.
_po will later contain everything that is needed for
translating your site. The file
_po/POTFILES should contain a list of files
that have translatable strings. You can create it by hand or easier like
$ qgoda po potfiles [info][config] reading configuration from '_qgoda.yaml' [info] creating “_po” [info] creating “_po/Makefile” [info] cloning git repository “https://github.com/gflohr/Template-Plugin-Gettext-Seed” Cloning into '/var/folders/54/b5jrb7hs2191y9nh2w5d0j7w0000gn/T/0ObN0NZ837'... remote: Enumerating objects: 21, done. remote: Counting objects: 100% (21/21), done. remote: Compressing objects: 100% (15/15), done. remote: Total 21 (delta 4), reused 0 (delta 0) Receiving objects: 100% (21/21), 11.18 KiB | 11.18 MiB/s, done. Resolving deltas: 100% (4/4), done. [info] creating “_po/PACKAGE” [info] creating “_po/PLFILES” [info] creating “_po/.gitignore” [info] creating “_po/qgoda.inc” [info] writing “_po/POTFILES” [info][plugin-loader] initializing plug-ins. [info] writing “_po/MDPOTFILES”
As you can see in line 5 a git repository with the necessary infrastructure
is cloned. All files reside in the directory
_po. The file
will contain a list of files that can potentially contain translatable strings.
There are two more
_po/PLFILES: If your side uses internatioinalized Perl code, list the file names here, so that their strings get automatically translated, too.
_po/MDPOTFILES: This will contain all of your content files that have to be translated if you also want to translate your content with PO files. See PO Translations for more information..
You may have noticed that Qgoda has also created a
Makefile for all the `make` aficionados
out there (like me). You can
_po and type
make to see
all the targets that the Makefile supports. You are,
however, on your own creating the various `POTFILES`,
pull requests welcome!
The main translation catalog is stored as a so-called PO template
TEXTDOMAIN is the textdomain you have
configured in the configuration variable
.pot file has the same format as normal
.po files only that it contains
only the original strings and no translations. You should never edit it,
because it gets overwritten, whenever you extract new strings.
You create the file like this:
$ qgoda po pot [info][config] reading configuration from '_qgoda.yaml' [info] execute: xgettext ...
You will see a lot of output which you can safely ignore as long as you don't see an error message.
linguas: - en - fr - de
You also have to initialize a
.po file for it:
$ cd /path/to/your/site $ cd _po $ msginit --input=com.example.www.pot --locale=de The new message catalog should contain your email address, so that users can give you feedback about the translations, and so that maintainers can contact you in case of unexpected technical problems. Is the following your email address? email@example.com Please confirm by pressing Return, or enter your email address. firstname.lastname@example.org Retrieving http://translationproject.org/team/index.html... done. A translation team for your language (de) does not exist yet. If you want to create a new translation team for de, please visit http://www.iro.umontreal.ca/contrib/po/HTML/teams.html http://www.iro.umontreal.ca/contrib/po/HTML/leaders.html http://www.iro.umontreal.ca/contrib/po/HTML/index.html Created de.po.
You will be prompted for your email address so that the copyright
information in the
.po file can be initialized.
msginit has two mandatory arguments (see line 3 above):
--inputis the name of your
--localeis the language identifier
The command has created a
.po file for your language (see line 19) that
can now be translated.
When strings are added or modified, the translations have to be updated. That requires the following steps:
POTFILESthat contains the updated list of source files
.potfile that contains the new set of translatable strings
.potfile into the existing
.potranslation files with the command
This is done with
qgoda po update-po:
$ qgoda po update-po [info][config] reading configuration from '_qgoda.yaml' [info] merging de.po [info] rename “de.po” to “de.old.po” [info] execute: msgmerge de.old.po com.example.www.pot --previous -o de.po . done. [info] unlink “de.old.po”
When you have more content to translate this may take considerable time
msgmerge is trying to do the merge in a smart manner so that you
don't lose existing translations.
After this step, your translation files are up-to-date and can be translated.
.po format is accepted by many professional translators. If you want
to translate the file yourself, do not use your normal text editor (unless
it is emacs) but use a specialized tool for it. Search the web for
Editor and you will find a number of free programs.
For now, just open the
.po file in your editor. You will see lots of
entries like this:
#: ../_views/partials/body.html:4 msgid "Hello, world!" msgstr "Hallo, Welt!"
The string after
msgstr is the translation. Try to translate at least one
string that is easy to recognize, when you rebuild your site.
.po files are not immediately used for looking up translations but are
compiled into binary
.mo files. The compilation also checks the
for syntax errors and semantic errors.
You can perform this step with
qgoda po mo:
$ qgoda po update-mo [info][config] reading configuration from '_qgoda.yaml' [info] execute: msgfmt --check --statistics --verbose -o de.gmo de.po de.po:7: warning: header field 'Project-Id-Version' still has the initial default value de.po: 1 translated message.
You can fix the warning (line 4) by editing the first entry of the
file and fill in the missing information.
In the last line you will see statistics about your translations, in particular the number of translated and untranslated strings and fuzzy translations.
Fuzzy translations are translations that have been automatically created
msgmerge but have to be reviewed by a human. These translations
are *not* used until the fuzzy mark is removed from them. See the documentation
of your PO editor for more information.
The last step is to install and use the translation:
$ qgoda po install [info][config] reading configuration from '_qgoda.yaml' [info] create directory “/path/to/your/site/LocaleData/de/LC_MESSAGES” [info] copy “de.gmo” to “/path/to/your/site/LocaleData/de/LC_MESSAGES/com.example.www.mo”
The next time you rebuild your site with
qgoda watch or
the translated strings should be visible in their respective document
By default, translations are cached, and new translations are not automatically
visible. You can prevent that at the prize of a minimal performance penalty
by setting the configuration variable
po.reload to 1.
The above explanation is relatively detailed. Under normal circumstances you
can just type
qgoda po all before everything that has to do with
translations and you're done.