r3 enables you to easily internationalize your web pages. Translations are performed from the command line or via the GUI. Translation terms are looked up in a search path, just as templates are. And as with templates, r3 uses the first encountered match.
View all current translated and untranslated strings using r3 translation list:
$ r3 translation list
cars/ca
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cars/fr
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cars/generic_intl
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cars/jp
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Japanese Header: Japanese Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cars/us
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/ca
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/fr
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/generic_intl
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/jp
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Japanese Header: Japanese Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/us
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
generic_product/ca
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
generic_product/fr
Cars Navigation: Cars Navigation
Cars Site Branding: Cars Site Branding
Container: Container
Content: Content
Cookery Navigation: Cookery Navigation
Cookery Site Branding: Cookery Site Branding
Core Branding: Core Branding
Header: Header
Navigation: Navigation
Site Branding: Site Branding
Wine Navigation: Wine Navigation
generic_product/generic_intl
Cars Navigation: Cars Navigation
Cars Site Branding: Cars Site Branding
Container: Container
Content: Content
Cookery Navigation: Cookery Navigation
Cookery Site Branding: Cookery Site Branding
Core Branding: Core Branding
Header: Header
Navigation: Navigation
Site Branding: Site Branding
Wine Navigation: Wine Navigation
generic_product/jp
Cars Navigation: Cars Navigation
Cars Site Branding: Cars Site Branding
Container: Container
Content: Content
Cookery Navigation: Cookery Navigation
Cookery Site Branding: Cookery Site Branding
Core Branding: Core Branding
Header: Header
Japanese Header: Japanese Header
Navigation: Navigation
Site Branding: Site Branding
Wine Navigation: Wine Navigation
generic_product/us
Cars Navigation: Cars Navigation
Cars Site Branding: Cars Site Branding
Container: Container
Content: Content
Cookery Navigation: Cookery Navigation
Cookery Site Branding: Cookery Site Branding
Core Branding: Core Branding
Header: Header
Navigation: Navigation
Site Branding: Site Branding
Wine Navigation: Wine Navigation
wine/ca
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
wine/fr
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
wine/generic_intl
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
wine/jp
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Japanese Header: Japanese Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
wine/us
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
The [i] after a term means that the translation,
while visible at a particular location, is actually inherited from a
more generic location.
You can perform translation from the r3 CLI using r3 translation set for individual terms. However a more common approach would be to save the translations for a particular site, or all sites, as an XLIFF file and to send that file to a third party translator. Use the command r3 translation save to save all translations. For example:
$ r3 translation save all alltrans.xml all dictionary data saved in file 'alltrans.xml'
Looking at the resulting alltrans.xml we
see:
<xliff version='1.1'
xmlns='http://developer.yahoo.com/xmlns/r3/xliff'
xmlns:sup='http://developer.yahoo.com/xmlns/r3/xliff-sup-1'>
<file original='generic_product/fr/generic'
source-language='en'
target-language='fr'
datatype='plaintext'>
<body>
<trans-unit id='1'>
<source>Cars Navigation</source>
<target>Cars Navigation</target>
</trans-unit>
<trans-unit id='2'>
<source>Cars Site Branding</source>
<target>Cars Site Branding</target>
</trans-unit>
<trans-unit id='3'>
<source>Container</source>
<target>Container</target>
</trans-unit>
<trans-unit id='4'>
<source>Content</source>
<target>Content</target>
</trans-unit>
<trans-unit id='5'>
<source>Cookery Navigation</source>
<target>Cookery Navigation</target>
</trans-unit>
<trans-unit id='6'>
<source>Cookery Site Branding</source>
<target>Cookery Site Branding</target>
</trans-unit>
<trans-unit id='7'>
<source>Core Branding</source>
<target>Core Branding</target>
</trans-unit>
<trans-unit id='8'>
<source>Header</source>
<target>Header</target>
</trans-unit>
<trans-unit id='9'>
<source>Navigation</source>
<target>Navigation</target>
</trans-unit>
<trans-unit id='10'>
<source>Site Branding</source>
<target>Site Branding</target>
</trans-unit>
<trans-unit id='11'>
<source>Wine Navigation</source>
<target>Wine Navigation</target>
</trans-unit>
</body>
</file>
</xliff>
Looking at alltrans.xml, you can see that
many of the translations are at different inherited generic levels—the
original attribute of the file tag denotes the location of
the translation. In the course of developing this project we ran a
generate for all targets including the generic ones that caused some
translations to be inserted at the generic level.
There are two ways to resolve the inheritance problem:
Run r3 translation clear to completely clear the dictionary; then carefully regenerate each desired target, remembering to generate parents first.
Export each site's dictionary separately, enabling inheritance, and then merge the results back in.
To export a dictionary separately, use r3 translation
save inherited. For example, saves
generic_product/fr's dictionary to the file
fr.xml. Looking at
fr.xml:
$ r3 translation save inherited generic_product/fr fr.xml generic_product/fr and inherited dictionary data saved in file 'fr.xml'
Even though many translations were really at a more generic
level, r3 behaves as though they are all at the fr
level.
<?xml version="1.0" encoding="UTF-8"?>
<xliff version='1.1'
xmlns='http://developer.yahoo.com/xmlns/r3/xliff'
xmlns:sup='http://developer.yahoo.com/xmlns/r3/xliff-sup-1'>
<file original='generic_product/fr/generic'
source-language='en'
target-language='fr'
datatype='plaintext'>
<body>
<trans-unit id='1'>
<source>Cars Navigation</source>
<target>Cars Navigation</target>
</trans-unit>
<trans-unit id='2'>
<source>Cars Site Branding</source>
<target>Cars Site Branding</target>
</trans-unit>
<trans-unit id='3'>
<source>Container</source>
<target>Container</target>
</trans-unit>
<trans-unit id='4'>
<source>Content</source>
<target>Content</target>
</trans-unit>
<trans-unit id='5'>
<source>Cookery Navigation</source>
<target>Cookery Navigation</target>
</trans-unit>
<trans-unit id='6'>
<source>Cookery Site Branding</source>
<target>Cookery Site Branding</target>
</trans-unit>
<trans-unit id='7'>
<source>Core Branding</source>
<target>Core Branding</target>
</trans-unit>
<trans-unit id='8'>
<source>Header</source>
<target>Header</target>
</trans-unit>
<trans-unit id='9'>
<source>Navigation</source>
<target>Navigation</target>
</trans-unit>
<trans-unit id='10'>
<source>Site Branding</source>
<target>Site Branding</target>
</trans-unit>
<trans-unit id='11'>
<source>Wine Navigation</source>
<target>Wine Navigation</target>
</trans-unit>
</body>
</file>
</xliff>
Edit the translation XML file, and put in your translations for each term. In our example each term has simply been wrapped in square brackets with the token fr, so "Wine Navigation" becomes "[fr Wine Navigation]" etc.
Merge the translations you did in the previous step into the dictionary:
$ r3 translation merge fr.xml dictionary data merged from file 'fr.xml'
The above merge operation is actually quite subtle. For every
source value, r3 searches the
inheritance chain to see if the value already exists. If found,
r3 compares the translations and,
if they are the same, doesn't enter the record into the database. If
r3 doesn't find a source or the
translation of the found source differs, then r3 inserts the record into the dictionary at
the declared location (generic_product/fr in
this case).
Look at the entire dictionary again. You can see that those
translations have become available for all fr and
ca sites.
$ r3 translation list
cars/ca
Cars Navigation: [fr Cars Navigation] [i]
Cars Site Branding: [fr Cars Site Branding] [i]
Container: [fr Container] [i]
Content: [fr Content] [i]
Cookery Navigation: [fr Cookery Navigation] [i]
Cookery Site Branding: [fr Cookery Site Branding] [i]
Core Branding: [fr Core Branding] [i]
Header: [fr Header] [i]
Navigation: [fr Navigation] [i]
Site Branding: [fr Site Branding] [i]
Wine Navigation: [fr Wine Navigation] [i]
cars/fr
Cars Navigation: [fr Cars Navigation] [i]
Cars Site Branding: [fr Cars Site Branding] [i]
Container: [fr Container] [i]
Content: [fr Content] [i]
Cookery Navigation: [fr Cookery Navigation] [i]
Cookery Site Branding: [fr Cookery Site Branding] [i]
Core Branding: [fr Core Branding] [i]
Header: [fr Header] [i]
Navigation: [fr Navigation] [i]
Site Branding: [fr Site Branding] [i]
Wine Navigation: [fr Wine Navigation] [i]
cars/generic_intl
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cars/jp
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Japanese Header: Japanese Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cars/us
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/ca
Cars Navigation: [fr Cars Navigation] [i]
Cars Site Branding: [fr Cars Site Branding] [i]
Container: [fr Container] [i]
Content: [fr Content] [i]
Cookery Navigation: [fr Cookery Navigation] [i]
Cookery Site Branding: [fr Cookery Site Branding] [i]
Core Branding: [fr Core Branding] [i]
Header: [fr Header] [i]
Navigation: [fr Navigation] [i]
Site Branding: [fr Site Branding] [i]
Wine Navigation: [fr Wine Navigation] [i]
cookery/fr
Cars Navigation: [fr Cars Navigation] [i]
Cars Site Branding: [fr Cars Site Branding] [i]
Container: [fr Container] [i]
Content: [fr Content] [i]
Cookery Navigation: [fr Cookery Navigation] [i]
Cookery Site Branding: [fr Cookery Site Branding] [i]
Core Branding: [fr Core Branding] [i]
Header: [fr Header] [i]
Navigation: [fr Navigation] [i]
Site Branding: [fr Site Branding] [i]
Wine Navigation: [fr Wine Navigation] [i]
cookery/generic_intl
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/jp
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Japanese Header: Japanese Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
cookery/us
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
generic_product/ca
Cars Navigation: [fr Cars Navigation] [i]
Cars Site Branding: [fr Cars Site Branding] [i]
Container: [fr Container] [i]
Content: [fr Content] [i]
Cookery Navigation: [fr Cookery Navigation] [i]
Cookery Site Branding: [fr Cookery Site Branding] [i]
Core Branding: [fr Core Branding] [i]
Header: [fr Header] [i]
Navigation: [fr Navigation] [i]
Site Branding: [fr Site Branding] [i]
Wine Navigation: [fr Wine Navigation] [i]
generic_product/fr
Cars Navigation: [fr Cars Navigation]
Cars Site Branding: [fr Cars Site Branding]
Container: [fr Container]
Content: [fr Content]
Cookery Navigation: [fr Cookery Navigation]
Cookery Site Branding: [fr Cookery Site Branding]
Core Branding: [fr Core Branding]
Header: [fr Header]
Navigation: [fr Navigation]
Site Branding: [fr Site Branding]
Wine Navigation: [fr Wine Navigation]
generic_product/generic_intl
Cars Navigation: Cars Navigation
Cars Site Branding: Cars Site Branding
Container: Container
Content: Content
Cookery Navigation: Cookery Navigation
Cookery Site Branding: Cookery Site Branding
Core Branding: Core Branding
Header: Header
Navigation: Navigation
Site Branding: Site Branding
Wine Navigation: Wine Navigation
generic_product/jp
Cars Navigation: Cars Navigation
Cars Site Branding: Cars Site Branding
Container: Container
Content: Content
Cookery Navigation: Cookery Navigation
Cookery Site Branding: Cookery Site Branding
Core Branding: Core Branding
Header: Header
Japanese Header: Japanese Header
Navigation: Navigation
Site Branding: Site Branding
Wine Navigation: Wine Navigation
generic_product/us
Cars Navigation: Cars Navigation
Cars Site Branding: Cars Site Branding
Container: Container
Content: Content
Cookery Navigation: Cookery Navigation
Cookery Site Branding: Cookery Site Branding
Core Branding: Core Branding
Header: Header
Navigation: Navigation
Site Branding: Site Branding
Wine Navigation: Wine Navigation
wine/ca
Cars Navigation: [fr Cars Navigation] [i]
Cars Site Branding: [fr Cars Site Branding] [i]
Container: [fr Container] [i]
Content: [fr Content] [i]
Cookery Navigation: [fr Cookery Navigation] [i]
Cookery Site Branding: [fr Cookery Site Branding] [i]
Core Branding: [fr Core Branding] [i]
Header: [fr Header] [i]
Navigation: [fr Navigation] [i]
Site Branding: [fr Site Branding] [i]
Wine Navigation: [fr Wine Navigation] [i]
wine/fr
Cars Navigation: [fr Cars Navigation] [i]
Cars Site Branding: [fr Cars Site Branding] [i]
Container: [fr Container] [i]
Content: [fr Content] [i]
Cookery Navigation: [fr Cookery Navigation] [i]
Cookery Site Branding: [fr Cookery Site Branding] [i]
Core Branding: [fr Core Branding] [i]
Header: [fr Header] [i]
Navigation: [fr Navigation] [i]
Site Branding: [fr Site Branding] [i]
Wine Navigation: [fr Wine Navigation] [i]
wine/generic_intl
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
wine/jp
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Japanese Header: Japanese Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
wine/us
Cars Navigation: Cars Navigation [i]
Cars Site Branding: Cars Site Branding [i]
Container: Container [i]
Content: Content [i]
Cookery Navigation: Cookery Navigation [i]
Cookery Site Branding: Cookery Site Branding [i]
Core Branding: Core Branding [i]
Header: Header [i]
Navigation: Navigation [i]
Site Branding: Site Branding [i]
Wine Navigation: Wine Navigation [i]
Repeat the process for the other intls, always exporting the
generic_product/$intl location to
$intl.xml, replacing the translations in that
file, and merging them back. For ca make only a token
translation of the "Cars Site Branding" and leave the rest of the
translations alone.
Then generate all the files again and examine the results.
$ r3 generate -a
Your final results should look something like this:
