ftw.recipe.translations 1.2.6

Mass export / import of translations into Google Docs Spreadsheets

ftw.recipe.translations provides mass theese features:

• bin/i18n-build: Package rebuilding script for installing in a single package.

• bin/masstranslate: export / import of translations into / from Google Docs spreadsheets for letting translators translate in a better environment.

Table of Contents

• bin/i18n-build

  • Installation and configuration

  • Usage

• bin/masstranslate

  • Installation and Configuration

  • Google authentication and authorization

  • The sync command

  • The upload command

  • The download command

• Translation headers

• Links

• Copyright

• Changelog

  • 1.2.6 (2017-01-09)

  • 1.2.5 (2015-11-24)

  • 1.2.4 (2015-11-17)

  • 1.2.3 (2015-04-16)

  • 1.2.2 (2015-03-13)

  • 1.2.1 (2014-12-14)

  • 1.2.0 (2014-06-05)

  • 1.1.1 (2014-03-05)

  • 1.1.0 (2014-03-05)

  • 1.0.2 (2014-01-31)

  • 1.0.1 (2014-01-31)

  • 1.0.0 (2014-01-31)

bin/i18n-build

The i18n-build script is installed for a single package. When executed, all languages of all domains translated in this package are rebuilt.

The script expectes exactly one primary domain. The domain name is expected to be equal to the package name (configurable).

What the script does:

• The script rebuilds the primary package using i18ndude: it scans for translated strings in the code and rebuilds the .pot of the primary domain.

• It syncs the .po-files of all domains in all languages.

Installation and configuration

For installation simply use the zc.buildout recipe ftw.recipe.translations:package:

[buildout]
parts = i18n-build

[i18n-build]
recipe = ftw.recipe.translations:package
package-name = my.package

Options:

package-name

The setuptools-name of the package (required).

i18n-domain

The name of the primary domain of this package (optional, defaults to the package name).

package-namespace

The package namespace used for scanning the code when rebuilding the primary domain (optional, defaults to the the package name).

Full example:

[buildout]
parts = i18n-build

[i18n-build]
recipe = ftw.recipe.translations:package
package-name = MyPackage
i18n-domain = mypackage
package-namespace = my.package

Usage

Rebuilding and syncing all existing languages:

$ bin/i18n-build
Rebuilding .../my/package/locales/mypackage.pot
.../my/package/locales/de/LC_MESSAGES/mypackage.po: 0 added, 2 removed
.../my/package/locales/en/LC_MESSAGES/mypackage.po: 1 added, 2 removed
.../my/package/locales/de/LC_MESSAGES/plone.po: 1 added
.../my/package/locales/en/LC_MESSAGES/plone.po: 1 added

Creating translations (.po-files) for new languages:

$ bin/i18n-build fr it
Rebuilding .../my/package/locales/mypackage.pot
.../my/package/locales/de/LC_MESSAGES/mypackage.po: 0 added, 2 removed
.../my/package/locales/en/LC_MESSAGES/mypackage.po: 1 added, 2 removed
.../my/package/locales/fr/LC_MESSAGES/mypackage.po: 80 added, 0 removed
.../my/package/locales/it/LC_MESSAGES/mypackage.po: 80 added, 0 removed
.../my/package/locales/de/LC_MESSAGES/plone.po: 1 added
.../my/package/locales/en/LC_MESSAGES/plone.po: 1 added
.../my/package/locales/fr/LC_MESSAGES/plone.po: 3 added, 0 removed
.../my/package/locales/it/LC_MESSAGES/plone.po: 3 added, 0 removed

bin/masstranslate

The masstranslate script is installed in a buildout which checks out all relevant packages into an src-directory (e.g. using mr.developer).

You then can upload all translations of all packages in the source-directory into a Googlea spreadsheet for translation. When the translation is done in the Google spreadsheet the script can download all translations and sync them back to the right place in the packages.

Installation and Configuration

Using the buildout recipe generates a script bin/masstranslate:

[buildout]
parts = translations

[translations]
recipe = ftw.recipe.translations [masstranslate]
spreadsheet = https://docs.google.com/spreadsheet/ccc?key=0AgoYEZSDYCg1dEZvVGFTRUc3RDd6123DAFDER

The generated bin/masstranslate script is preconfigured with the configured spreadsheet url and applies to all .po-files in the ./src directory by default.

Google authentication and authorization

Google auth is implemented using OAuth2. This means you require to have an application set up in your Google API Console or at least have the application secrets (.json) of such an application. The application secrets need to be copied to ~/.buildout/ftw.recipe.translations.json. For instructions for creating a Google application see the Wiki page.

When using the upload and download commands, the OAuth2 authentication is done with the configure application. The browser is opened and the user can grant access for the application to his Google Drive. The received ticket is stored in the users keyring / keychain.

If the server in your running this script do not have a web browser (for instance you are running it in a shared computer logged-in through SSH), the browser that pops-up is unable to handle the authorization process or if you prefer to authorize the application using your own web browser; add the --noauth_local_webserver=True parameter to the script. Using this option the script will show a URL which you should open with your browser manualy, and later enter the authorization code showed in that browser back in the console.

The sync command

The bin/masstranslate script provides a sync command for rebuilding primary-domain .pot-files and syncing them with all languages.

As primary domain the package name (folder in the src directory) is expected. Primary domains are rebuilt (the package is searched for translatable strings) and [domain]-manual.pot-files in the locales directory are automatically merged. Non-primary domains are never rebuilt and expected to be updated manually.

All domains are then sync to all existing languages.

Example:

./bin/masstranslate sync

Creating new languages for all packages and domains is as easy as passing a positional argument:

./bin/masstranslate sync de

The upload command

With the upload command translations can easily be extracted from the .po-Files and uploaded into a Google spreadsheet. The upload command always creates a new worksheet in the Google spreadsheet, so that existing data is never overwritten.

See the Configuration section on how to configure the spreadsheet URL.

With positional arguments the languages to be translated can be specificied. Each defined language is included in the spreadsheet. If a message is translated in all languages, the message is not uploaded unless the --all keyword is used.

Additional languages, which are not checked for existing translations, can be added using the --additional-languages keyword, those may be useful for the translator.

Example:

./bin/masstranslate upload de fr --additional-languages en es
Spreadsheet: https://docs.google.com/spreadsheet/ccc?key=0AgoYEZ....
Loading translations
Starting Upload
1 of 191 (0%): Upload
9 of 191 (4%): Upload
...
Finished Upload
Uploaded into worksheet "013: 2014-01-31"

The download command

The download command syncs translations back from the spreadsheet into the .po-files in the source directory. When starting a download, the user is asked for the worksheet and languages to download. When a message is not translated in the spreadsheet, it is never updated in the .po-file.

Example:

./bin/masstranslate download
Please select a worksheet to download:
[1] 011: 2014-01-31
[2] 012: 2014-01-31
[3] 013: 2014-01-31

Please enter the spreadsheet number: 1
Please select the languages to synchronize:
- de
- fr

Enter one language code at a time, finish selection with an empty enter.
Language: fr
Language:

Translation headers

The syncing commands remove the .po-file header Domain, Language-Name and Language-Code. The reason for this behavior is that this package is primarely made for Plone packages and Plone does not read those headers (it gets the information from the paths, e.g. locales/[lang-code]/LC_MESSAGES/[domain].po). Because the headers are not relevant they are often not maintained properly and therefore usually wrong.

Links

• github project: https://github.com/4teamwork/ftw.recipe.translations

• Issues: https://github.com/4teamwork/ftw.recipe.translations/issues

• Pypi: http://pypi.python.org/pypi/ftw.recipe.translations

• Continuous integration: https://jenkins.4teamwork.ch/search?q=ftw.recipe.translations

Copyright

This package is copyright by 4teamwork.

ftw.recipe.translations is licensed under GNU General Public License, version 2.

Changelog

1.2.6 (2017-01-09)

• Support additional locales directories in subpackages. [jone]

• Support newest path.py version 10.0. [jone]

1.2.5 (2015-11-24)

• Require oauth2client (and six) dependencies only when installing the masstranslate recipe. This reduces dependency problems with six. [jone]

1.2.4 (2015-11-17)

• Update oauth2client version constraint in order to improve plone compatibility. [maethu]

1.2.3 (2015-04-16)

• Ignore no longer existing translations. [phgross]

1.2.2 (2015-03-13)

• Remove too strict six version pinning. six is pinned in Plone 4.3 KGS and newer. For older Plone versions it should be pinned down, e.g. to 1.4.0. [jone]

1.2.1 (2014-12-14)

• Retain Plone KGS compatibility by pinning oauth2client and six dependencies. [jone]

1.2.0 (2014-06-05)

• Masstranslate: add support for Google Oauth –noauth_local_webserver. This option is useful when there is no local browser (e.g. when connected through ssh to a server). [jone]

1.1.1 (2014-03-05)

• i18nbuild: Remove “Domain”, “Language-Code” and “Language-Name” headers. Plone does not need those headers, it takes informations from the path. The headers are usually not set correctly, so we just remove them. [jone]

1.1.0 (2014-03-05)

• Implement new bin/i18n-build recipe and script. [jone]

• Rename bin/translations to bin/masstranslate. [jone]

1.0.2 (2014-01-31)

• Fix previous brown bag releases: make buildout recipe work. [jone]

1.0.1 (2014-01-31)

• Fix missing distribution buildout error. [jone]

1.0.0 (2014-01-31)

• Initial implementation. [jone]