The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Qgoda-0.9.8
River stage zero No dependents
3 ++
/ Qgoda::Command::Po

NAME

qgoda po - Translation workflow based on PO files

SYNOPSIS

    qgoda po [<global options>] potfiles
    qgoda po [<global options>] pot
    qgoda po [<global options>] update-po
    qgoda po [<global options>] update-mo
    qgoda po [<global options>] install

Or for all of the above:

    qgoda po [<global options>] all

Try 'qgoda --help' for a description of global options.

DESCRIPTION

You will find tutorial style information for the internationalization (i18n) of Qgoda sites at http://www.qgoda.net/en/docs/i18n/. The following is rather meant as a quick reference.

Updates, compiles and installs translations. You need the GNU gettext tools as a prerequisite. They are available from your package manager as either "gettext-tools", "gettext-dev", or just "gettext". A package "gettext-runtime" is neither needed nor sufficient.

Everything related to translations resides in the directory _po, respectively the directory that the configuration variable paths.po in _config.yaml points to.

The directory is autmatically created and populated when necessary. It is necessary, if you use Template::Plugin::Gettext in one of your templates:

    [% USE gtx = Gettext('com.example.www', asset.lingua) %]

Creation of the _po directory is also triggered, if one of your site's markdown documents refers to another from the document variable master

    ---
    master: /en/about.md
    ---

Additionally, you must set the textdomain of your site in the configuration variable po.textdomain. The textdomain is the name under which translations are saved, usually the reverse domain name of your site. The textdomain for http://www.qgoda.net/ is for example net.qgoda.www.

The _po directory contains the following files:

PACKAGE

Contains the basic configuration of your site suitable for a Makefile and it is only needed if you use the Makefile. The file is auto-generated but then left untouched so that you can edit it to your needs.

In order to reset the file to the latest upstream version, delete it and then run qgoda build or qgoda watch once. Alternatively, run qgoda po reset.

The following configuration variables in _config.yaml are evaluated for the creation of PACKAGE:

linguas

An array of language codes, for example:

    linguas: [en, fr, de, bg]

The first value is assumed to be the base language of your site.

po.textdomain

Your site's textdomain, for example com.example.www.

po.msgid-bugs-address

An email address or web site for issuing errors in translatable strings. Translators will use that address for reporting problems with translating your site. See below for an example.

po.copyright-holder

The copyright holder that should be put into the header of the master translation file TEXTDOMAIN.pot.

po.xgettext

The xgettext(1) program on your system, defaults to just "xgettext".

po.xgettext_tt2

The xgettext-tt2(1) program on your system, defaults to just "xgettext-tt2".

po.qgoda

The qgoda(1) program on your system, defaults to just "qgoda".

po.msgmerge

The msgmerge(1) program on your system, defaults to just "msgmerge".

po.msgfmt

The msgfmt(1) program on your system, defaults to just "msgfmt".

For all configuration variables above that expect a command name, you can use a single value or a list, if you want to pass options to the command.

Example configuration for PACKAGE:

    linguas: [en, fr, de, bg]
    po:
      textdomain: com.example.www
      msgid_bugs_address: John Doe <po-bugs@example.com>
      copyright_holder: Acme Ltd. <http://www.example.com>

When you change the configuration, you have to either delete the generated files from the _po directory or run qgoda po reset in order to update them.

po-make.pl

This script is responsible for invoking the necessary helper programs as needed. Try perl po-make.pl --help for usage information if you want to run the program yourself. The result will be the same as using qgoda po TARGET.

Makefile

Does essentially the same as po-make.pl but is smarter at dependency handling. You can run the Makefile manually with the make(1) command or use the option --make (see <L/OPTIONS>) or set the configuration variable po.make.

PLFILES

A list of Perl source files for your site. If missing, an empty file is automatically generated but you have to maintain it manually.

MDPOTFILES

A list of Markdown documents found in your site that are referenced by documents that have to be translated. This file gets generated with the command "qgoda po potfiles".

By default, all assets with front matter are taken into account for the creation of this list. You can add additional search patterns to the configuration variable po.mdextra.

POTFILES

By default, all template files from the view directory (configuration variable paths.views) which defaults to _views are added. You can override that setting with the configuration variable po.views (this is not a typo). The default setting is:

po: views: - /_views/**

You can extend or reduce that list like this:

po: views: - /_views/** - !/_views/**/*.bak

Note, that this file will normally also contain a line for ./MDPOTFILES. This line has the effect that all translatable strings in Markdown files are also included in the master translation catalog.

qgoda.inc

Contains additional Makefile snippets needed by the Qgoda translation workflow. The file is only needed, when you use the Makefile.

*.po

For example fr.po, de.po and so on. You need one PO file for every language you have configured. Failure to do so will result in an error.

The simplest way of creating such a file from scratch is with the command:

    msginit --locale=fr --input=TEXTDOMAIN.pot

Replace "fr" with the language you need and TEXTDOMAIN.pot with the name of the master translation catalog that you have configured.

Note that you have to run <qgoda po pot> at least once before you can create PO files.

*.gmo

Contains compiled translations. These files are generated and you can safely delete them, whenever you want.

.gitignore

Tells git(1) which files to ignore. This file is auto-generated when missing but then left untouched.

In order to reset the file to the latest upstream version, delete it and then run qgoda build or qgoda watch once. Alternatively, run qgoda po reset.

The master translation catalog TEXTDOMAIN.pot is a generated file and generated files should normally be ignored by version control systems. No rule without an exception, master translation catalogs are conventionally not put into the ignore list. Rationale: Translators should not need any tools needed for creating .pot and .po files.

TARGETS

pot

Updates or creates the master translation catalog TEXTDOMAIN.pot.

update-po

Updates all .po files by merging in the current strings found in TEXTDOMAIN.pot. Note that you have to create the .po files yourself (try msginit --help).

This target implicitely includes the pot target (see above).

update-mo

Compiles the .po files containing the translations. Additionally a syntactic check is performed on the translation files and statistics about translated, untranslated and fuzzy entries is printed out.

This target implicitely includes the update-po and all preceding targets.

install

Installs translations. Running qgoda build or qgoda watch will now use these translations when rendering your site.

This target implicitely includes the update-mo and all preceding targets.

all

Does all of the above. Use this target if you just want to ensure that everything is up-to-date and documents are translated to the extent that translations are available.

reset

Overwrites the files po-make.pl and Makefile https://github.com/gflohr/Template-Plugin-Gettext-Seed/ and resets PACKAGE, qgoda.yaml, qgoda.inc, and .gitignore to a vanilla state.

OPTIONS

-h, --help

Show this help page and exit.

CONFIGURATION

If you set the configuration variable po.make to the name of a make(1) executable on your system, the Makefile in _po is executed instead of emulating the Makefile behavior with Perl.

The Makefile includes all files in the _po directory that match *.inc so that you can easily extend it.

SEE ALSO

http://www.qgoda.net/en/docs/i18n/, xgettext-tt2, Template::Plugin::Gettext, xgettext(1), msgmerge(1), msgfmt(1), git(1)

QGODA

Part of Qgoda.