45
r3 User Guide

r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

  • Upload
    others

  • View
    9

  • Download
    0

Embed Size (px)

Citation preview

Page 1: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

r3 User Guide

Page 2: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

r3 User Guide

Page 3: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Table of Contents1. Introduction .................................................................................................................... 1

What is r3? ................................................................................................................. 1How does r3 work? ...................................................................................................... 1r3 Components ............................................................................................................ 3Templates ................................................................................................................... 4Translation ................................................................................................................. 4Inheritance and Search Paths .......................................................................................... 4

2. Installation and Configuration ............................................................................................. 6Deciding on a Database ................................................................................................ 6Installing and Configuring r3 ......................................................................................... 6Configuring the r3 GUI ................................................................................................. 7

3. Getting Started ................................................................................................................. 84. Using the r3 Command Line Interface ................................................................................ 11

Creating Dimension Elements ...................................................................................... 11Products and Intls .............................................................................................. 11Targets ............................................................................................................. 13

Generating Files ........................................................................................................ 14Working With Templates ............................................................................................. 15

Creating and Editing Templates ............................................................................ 15Specializing Templates ........................................................................................ 18Promoting Templates .......................................................................................... 23

Working With Translations ........................................................................................... 24Exporting and Importing Translations .................................................................... 29

5. Using the r3 GUI ............................................................................................................ 37Dimensions Tab ......................................................................................................... 37Targets Tab ............................................................................................................... 37Translations Tab ........................................................................................................ 38Generate Tab ............................................................................................................. 41

iii

Page 4: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

List of Figures1.1. Yahoo! home pages for US, UK, and Japan ......................................................................... 25.1. Dimensions Tab ........................................................................................................... 375.2. Targets Tab ................................................................................................................. 385.3. Displaying Information about a Target .............................................................................. 385.4. Adding a Translation ..................................................................................................... 395.5. Searching for a Term ..................................................................................................... 395.6. Managing Translations .................................................................................................. 405.7. Managing Translation Inheritance ................................................................................... 405.8. Generate Tab ............................................................................................................... 415.9. Generating Files ........................................................................................................... 41

iv

Page 5: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Chapter 1. IntroductionWhat is r3?

r3 is an extensible tool for creating, managing, and localizing templates and translations. It can be controlledusing both web and command line interfaces. r3 generates text-based files for use in internationalized ap-plications. These outputs may take the form of templates, configuration files or even source code. r3 cansave and load translation data in XLIFF format. It can be extended using the stickleback plugin engine. Itcan also be embedded into third party applications.

How does r3 work?r3 generates its targets by first searching for and then combining templates and translations. r3 managesthese resources in the context of a number of categories like project (mail or search), locale (uk or us)and page (index.php or about.js). It uses an inheritance hierarchy to create a search path to each of a target'sparts. This allows you to reuse page elements from category to category and lets you create specializedversions of others.

Here's an example that uses the Yahoo! home pages for three different locales: the US, the UK, and Japan.You can see that the US and UK home pages have the same look and feel, but with small differences. Theyshare the same page layout but with customized header, navigation, and content. The Japan home pagelooks very different, but you can still see some similarities -- note, for example, the home page logo andthe search box.

1

Page 6: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Figure 1.1. Yahoo! home pages for US, UK, and Japan

You could create each of these pages in a completely customized manner, of course. But the pages shownabove change regularly, and that sort of customized work becomes impractical, particularly as the websitesgrow in complexity. The ideal then is to reuse common components as much as possible, and still allowroom for differentiation.

Through r3, you can arrange your files in small, logical units suitable for reuse. This spares the webserverthe processing costs associated with reassembly and translation. And because most markup can be separatedfrom procedural code, you can manage the HTML fragments without the risk of breaking functional code.When it comes time to push out changes to your sites, r3 generates the targets for deployment by combiningtemplate files, filling them with the (translated) data, to form the larger HTML. All this happens prior todeployment, which means the web application itself can be left to process the user requests.

Finally, note that r3 doesn't have to be used to localize websites, though that is the most common application.It is has been generalized so it can be used in any text-file based context to generate families of related,but different, text-based output. And the output you generate doesn't have to differ along language or inter-national lines. There can and often are other axes of differentiation, such as different product lines or dif-ferent kinds of branding.

2

Introduction

Page 7: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

r3 ComponentsAn r3 project consists of the following components:

• database

• domains

• dimensions

• targets

The database provides a repository for storing domains, dimensions, path specifications, and translations.

Domains are the components that combine together to build targets. They are expressed as locations in thefile structure and are searchable. There are three types of domains:

• templates—A template is a file (*.ros) that is processed by r3 system to create a target. Templatescan containing special markup (for example, for translations).

• translations—Translation repositories. Translations are words or strings mapped from one languageto another. Dictionaries are stored in the database as XLIFF and exported as XML.

• pages—Pages contain information about a target, including its location in the search path.

Dimensions are the types of places that r3 searches for domain objects. There are three types of dimensions:

• product—The product dimension describes the purpose (such as the brand) of a site.

• intl—The intl dimension describes a locale. They are used to specify the language and translation re-quirements for a project

• page—The page dimension describes the individual file level components of a site.

Using the programming language paradigm, dimensions are types, and the instances of a dimension aredimension elements. So, for example, you could express the product dimension with the elements 'mail','search', and 'shopping'; the intl dimension with 'en_US', 'fr_FR' and 'fr_CA'; the page dimension with 'in-dex.php', 'about.php', and so on.

3

Introduction

Page 8: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

TemplatesTemplate files have an .ros extension. They are specialized to "container level" (generic to the intl). Thedefault template name is taken from the target name. For example, the following command creats the targetblah.html in cheese/us/blah.html:

r3 target create cheese/us/blah.html

The template name is blah.html.ros, and the search path for template and translation is (1)cheese/us/blah.html, then (2) cheese/us/generic.

r3 looks for a template specific to a product, an intl, and a page. The actual locations that r3 looks in foreach product or intl are called elements. For example,

• Elements for product might be mail, search, and frontpage

• Elements for intl might be uk and fr

• Elements for page might be index.html or about.php

For example, when r3 builds a target, it looks for the template blah.ros, in frontpage/uk/in-dex.php/. As a template, blah.ros is a domain object. r3 looks for it in element frontpage in di-mension product, element uk in dimension intl, element blah.ros in dimension page.

By defining search paths when setting up a project, templates can be shared by different dimension elements.They can be moved or copied anywhere along the search path and then customized for a particular productor intl using a simple set of XML-like tags to change the generated output.

Templates can be based on any text-based source file, including PHP, HTML, JSP, XML, ASP, and TCL,and r3 creates the target files in the same format. Sophisticated users could even create Excel, Word orAcrobat files.

Translationr3 enables you to easily internationalize your web pages. Strings for translation are marked by the devel-opment team with r3's markup <r3:trans> in the source templates. When r3 generates its output files,all source translations are converted into the target strings.

r3 uses the industry-standard XLIFF file format for handling translations. The XLIFF file can be exportedto XML, sent to a translator, and then re-imported when the translations are done.

Inheritance and Search Pathsr3 recognizes three domains in which inheritance operates:

• templates

• translations

• pages

r3 maintains separate inheritance trees for each dimension in each domain. This means that templates canhave entirely different search paths from translations for each project, or for products or intls within aproject .

4

Introduction

Page 9: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Note

The page dimension has only one set of inheritance data for page specifications.

The path in a project's tree structure that r3 uses to search for a domain object is called a search path.Search paths enable fine-grained control over sharing of customized templates and translations. Duringfile generation, r3 requires a location to start searching for a domain object. If the object cannot be foundin the start location, it searches other related locations higher on the tree until it finds the domain objector reaches the top of the tree. If r3 reaches the top of the tree without finding the object it is searching for,it uses the topmost object.

5

Introduction

Page 10: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Chapter 2. Installation and ConfigurationOpen Source: We have tested the open source version of r3 on Fedora and BSD. Although they have notbeen tested, any Unix-like environment that can run PHP (including Mac OS-X) should be able to run r3.We have no plans to support Windows.

r3 requires PHP 5 with support for the PDO extension. It should also support either MySQL, SQLite, orboth (see the next section). PEAR is required in order to perform the installation, preferably with zlibsupport (for unpacking the pear .tgz file).

Deciding on a DatabaseBy default, r3 comes with a SQLite interface pre-configured. Alternatively, you can use a MySQL databasebackend. Each has its advantages, as described in this section.

• SQLite Advantages

• zero maintenance overhead

• private per-user databases

• Ideal for small, single-developer projects

• MySQL Advantages

• shared, networked databases, meaning shared projects

• better support for larger projects (more concurrency, larger data sets)

• Ideal for collaborative teams of developers on distributed hardware

Installing and Configuring r3Use the instructions below for installation:

1. Download the two packages that make up the complete application:

• Stickleback—The plugin engine which powers r3's command line interface. Download Sticklebackfrom http://sourceforge.net/projects/stickleback.

• r3—Download r3 from http://sourceforge.net/projects/rthree.

2. Install Stickleback and r3 (use version numbers shown here, or higher):

$ sudo sudo pear install -f stickleback-0_9_1.tgz install ok: channel://pear.php.net/stickleback-0.9.1$ sudo pear install -f --alldeps r3-0_9_1.tgz install ok: channel://pear.php.net/r3-0.9.1

3. Create an r3 working directory:

$ mkdir ~/r3

4. Have r3 prepare the directory for you.

6

Page 11: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

$ r3 setup setuphome ~/r3

5. Create an environment variable to remind r3 where its home is. For convenience you could put thisin a startup or login script.

$ export R3HOME=~/r3

6. Set up your databases:

a. To use r3 against MySQL, edit $R3HOME/r3.conf.xml and change the <DB> section torefer to mysql with the appropriate host, dbname etc.

Note

If you are setting up the MySQL database yourself, ensure that you have correctpermissions, etc, and that a MySQL server is running.

b. For either MySQL or SQLite, create local databases using the $R3HOME environment variable.

$ r3 setup installdb

Configuring the r3 GUITo use the r3 GUI, follow these steps

1. Run the installgui command to enable writing to the htdocs directory.

2. Ensure that your webserver is running.

Your r3 GUI home is now http://<yourserver>/r3gui.php.

7

Installation and Configuration

Page 12: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Chapter 3. Getting StartedBefore you set up your r3 project, there are several things to consider:

• Directory structure can be flat or grouped by common items. If grouped by common items you canshare translations and templates.

• Amount of translation needing to be done

• Separation of application logic and view. r3 is agnostic about the whether your view layer is separatedfrom the your application logic, but structurally, r3 best suits a system that has a clean distinctionbetween application and view logic.

This and the following chapter show how to use r3 using the example of creating a simple r3 project. r3is to be able to manage multiple websites in multiple languages, so our example project creates three sep-arate (but related) web products in four different languages.

Our example consists of the following products:

• cookery

• wine

• cars

The products are built for the following countries (intls):

• USA (us)

• French Canada (ca)

• France (fr)

• Japan (jp)

There is a good deal of interrelationship between some of these products and international sites (intls). Forexample, wine and cookery, can share similar styles (one could be a sub site of the other). Concerningintl, ca shares its language with fr and much of its culture with us. However, cars and cookery havelittle in common, as is the case with ca and jp.

Combining these two axes gives us 3 * 4 = 12 web sites to build:

• cookery/us

• cookery/ca

• cookery/fr

• cookery/jp

• wine/us

• wine/ca

• wine/fr

8

Page 13: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

• wine/jp

• cars/us

• cars/ca

• cars/fr

• cars/jp

To reduce complexity, each website will use R3 on a sngle page. Each page shares a simple, commonstructure:

Each component of that page has its own template:

9

Getting Started

Page 14: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

With this structure in mind, the next chapter, Using the r3 Command Line Interface, explains how to usethe command-line interface.

10

Getting Started

Page 15: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Chapter 4. Using the r3 Command LineInterface

This chapter continues with the example introduced in the previous chapter and discusses the commandline interface for r3. For a complete description of all r3 commands, refer to the r3 Reference Guide.

Note

The following chapter discusses r3's graphical user interface and builds on the example de-veloped here.

Creating Dimension Elementsr3 searches dimensions for domain objects.

Products and Intls1. Create the products and intls. Product, intl, and pages are examples of r3 dimensions. Products and

intls are created in much the same way. From the command line:

$ r3 dimension product create generic_productproduct generic_product created

The above command creates a product called generic_product. While not required, generic di-mension elements provide a common location for templates, target specifications, and translations.However, if you do not create generic dimension elements, inheritance defaults to whichever domainbeing searched is located at the top of the structure..

2. After creating generic_product, create the real products as descendants:

$ r3 dimension product create cookery -p generic_productproduct cookery created with parent generic_product for page, template and translation domains.

The -p flag stands for parent.

Created the rest of the products and intls in the same way:

$ r3 dimension product create wine -p cookeryproduct wine created with parent cookery for page, template and translation domains.$ r3 dimension product create cars -p generic_productproduct cars created with parent generic_product for page, template and translation domains.$ r3 dimension intl create generic_intlintl generic_intl created$ r3 dimension intl create us -p generic_intl...$ r3 dimension intl create ca -p us$ r3 dimension intl create fr -p generic_intl$ r3 dimension intl create jp -p generic_intl

This is the hierarchy for product:

11

Page 16: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

This is the hierarchy for intl:

3. Change French-speaking Canada to inherit its translations from fr.

r3 recognizes three domains in which inheritance operates. These domains correspond to the thingsthat r3 searches for:

• the template domain which is searched for templates

• the translation domain which is searched for translations

• the page domain which is searched for target page specifications

r3 maintains separate inheritance trees for each dimension in each domain (except for the page di-mension which, again, has only one set of inheritance data). When you create a product or intl andspecify its parent, the same parent relationship is set up for all domains. This is normally what youwant. However, in the special case of ca inheriting its translations from fr, you must change theinheritance relationship between ca and fr only for the translation domain. To do this:

$ r3 dimension intl parent ca set fr -d translationparent of intl ca changed to fr in the translation domain

12

Using the r3 Command Line Interface

Page 17: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

4. Change the parent of fr in the translation domain so that it doesn't inherit from generic_intl .

$ r3 dimension intl parent fr unset -f -d translationintl fr set with no parent in the translation domain$ r3 dimension intl parent us unset -d translationintl us set with no parent in the translation domain$ r3 dimension intl parent jp unset -d translationintl jp set with no parent in the translation domain

The -f flag is the "force" flag to change the parent of fr, because ca is a child of fr, and by defaultr3 refuses to move nodes with children.

The intls in the template and page domains retain the previous hierarchy, but for the transla-tion domain has following hierarchy:

Note

Note that generic_intl still exists in the translation domain. The existenceof intls, products and pages is independent of domains, it is only the inheritancerelationships between them that may differ between domains.

5. To view the inheritance structure for a given dimension within a given domain:

$ r3 dimension intl list -t translationjpusfr cageneric_intl

The -t flag says produce a "tree" view, and therefore needs an argument domain to get the inheritancedata.

TargetsAfter you set up inheritance, you can create targets. Use what looks like a Unix path to create a target,However, use the names of the product and intl for the target you want to create rather than directorynames:

13

Using the r3 Command Line Interface

Page 18: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

$ r3 target create generic_product/generic_intl/index.htmlpage created (1)

The above example created a target index.html for the generic_product and the generic_intl.This allows r3 to inherit its target specifications as well as its templates and translations. A targetat this location is also a target for all intls and products that inherit from it.

r3 creates an empty template for each created target, so there should now be a $R3HOME/templates/gen-eric_product/generic_intl/index.html.ros template that we can edit.

You can display information about the target you created using the command r3 target info. The inform-ation includes its location, template name, and searchpaths.

$ r3 target info generic_product/generic_intl/index.html

specified location -> generic_product/generic_intl/index.html Target name : index.html Location : generic_product/generic_intl/index.html Data found at : generic_product/generic_intl/index.html Template name : index.html.ros Path to template : /generic_product/generic_intl/generic/index.html.ros Search path for : page, template, translation - generic_product/generic_intl/index.html - generic_product/generic_intl/generic

Generating Files1. Before editing, check that the target exists for all sites by generating all your sites:

$ r3 generate -avgenerating cars/ca cars/ca/index.htmlgenerating cars/fr cars/fr/index.htmlgenerating cars/generic_intl cars/generic_intl/index.htmlgenerating cars/jp cars/jp/index.htmlgenerating cars/us cars/us/index.htmlgenerating cookery/ca cookery/ca/index.htmlgenerating cookery/fr cookery/fr/index.htmlgenerating cookery/generic_intl cookery/generic_intl/index.htmlgenerating cookery/jp cookery/jp/index.htmlgenerating cookery/us cookery/us/index.htmlgenerating generic_product/ca generic_product/ca/index.htmlgenerating generic_product/fr generic_product/fr/index.htmlgenerating generic_product/generic_intl generic_product/generic_intl/index.htmlgenerating generic_product/jp generic_product/jp/index.htmlgenerating generic_product/us generic_product/us/index.htmlgenerating wine/ca wine/ca/index.htmlgenerating wine/fr wine/fr/index.html

14

Using the r3 Command Line Interface

Page 19: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

generating wine/generic_intl wine/generic_intl/index.htmlgenerating wine/jp wine/jp/index.htmlgenerating wine/us wine/us/index.html

There is nothing special about generic_product and generic_intl beyond their root positionsin the inheritance trees. They are generated along with everything else.

2. Examine any of the generated files. You'll see that they are all identical, and contain only a simplecomment:

$ cat $R3HOME/htdocs/cookery/us/index.html<!-- autogenerated default template: index.html.ros -->

Working With TemplatesInheritance enables (potentially hundreds of) targets to share domains and eliminates duplication of effortfor pages with minor variations.

Templates can be copied or moved to a specialized location and then customized. This enables you tocontrol generated output. Template customization is accomplished using a set of XML-like tags. The mostcommonly used tags are <r3:include> for adding a sub-template, and <r3:trans> for identifyingtext to be translated. For more information about r3 markup, see the r3 Reference Guide.

You bracket terms or strings that you want to appear in a different language with the r3 markup<r3:trans> </r3:trans> in the source templates. During file generation, r3 notes these speciallymarked items and inserts the appropriate translation from the dictionary file.

Creating and Editing Templates1. We already created a template using the r3 target create command, in the section “Targets” [13]. Use

your favorite editor to edit your template (our example uses vim as the editor).

$ vim $R3HOME/templates/generic_product/generic_intl/index.html/index.html.ros

Note

If you've exported the environment variable $VISUAL or $EDITOR, you can accomplishthe same thing with the r3 template edit command.

$ r3 template edit generic_product/generic_intl/index.html index.html.ros

However you decide to open the file, you'll see it consists of a single comment:

<!-- autogenerated default template: index.html.ros -->

2. Delete the comment and enter the following HTML:

<html><head></head><body><table width="100%" border="2"><tr><th colspan="2">Container: <r3:trans>Container</r3:trans></th>

15

Using the r3 Command Line Interface

Page 20: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

</tr><tr><td colspan="2"><r3:include path="header.ros" /></td></tr><tr><td width="30%"><r3:include path="navigation.ros" /></td><td width="70%"><r3:include path="content.ros" /></td></tr></table></body></html>

3. Note the three <r3:include /> directives. Following our example's structure, index.html.roscorresponds to the "container" component. You need to create the other templates too. Let's do thatnow, using the r3 template create command.

$ r3 template create generic_product/generic_intl/index.html header.rostemplate navigation.ros is created at /tmp/r3/templates/generic_product/generic_intl/index.html/header.ros

$ r3 template create generic_product/generic_intl/index.html navigation.rostemplate navigation.ros is created at /tmp/r3/templates/generic_product/generic_intl/index.html/navigation.ros

$ r3 template create generic_product/generic_intl/index.html content.rostemplate content.ros is created at /tmp/r3/templates/generic_product/generic_intl/index.html/content.ros

$ r3 template create generic_product/generic_intl/index.html core_branding.rostemplate content.ros is created at /tmp/r3/templates/generic_product/generic_intl/index.html/core_branding.ros

$ r3 template create generic_product/generic_intl/index.html site_branding.rostemplate content.ros is created at /tmp/r3/templates/generic_product/generic_intl/index.html/site_branding.ros

Now you can open these files to edit them. Let's start with header.ros:

$ r3 template edit generic_product/generic_intl/index.html header.ros

Remove the autogenerated comment, and edit the content to look like this:

<table width="100%" border="2"><tr><th colspan=2>Header: <r3:trans>Header</r3:trans></th><tr><td><r3:include path="core_branding.ros" /></td><td><r3:include path="site_branding.ros" /></td></tr></table>

4. Likewise, edit the following files with these changes:

• navigation.ros ($R3HOME/templates/generic_product/generic_intl/in-dex.html/navigation.ros):

Navigation: <r3:trans>Navigation</r3:trans>

• content.ros ($R3HOME/templates/generic_product/generic_intl/in-dex.html/content.ros):

Content

16

Using the r3 Command Line Interface

Page 21: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

• core branding.ros $R3HOME/templates/generic_product/generic_in-tl/index.html/core_branding.ros:

Core Branding: <r3:trans>Core Branding</r3:trans>

• site_branding.ros $R3HOME/templates/generic_product/generic_in-tl/index.html/site_branding.ros:

Site Branding: <r3:trans>Site Branding</r3:trans>

5. Now generate all targets:

$ r3 generate -agenerating cars/cagenerating cars/frgenerating cars/generic_intlgenerating cars/jpgenerating cars/usgenerating cookery/cagenerating cookery/frgenerating cookery/generic_intlgenerating cookery/jpgenerating cookery/usgenerating generic_product/cagenerating generic_product/frgenerating generic_product/generic_intlgenerating generic_product/jpgenerating generic_product/usgenerating wine/cagenerating wine/frgenerating wine/generic_intlgenerating wine/jpgenerating wine/us

6. Examine one of the generated files:

$ cat $R3HOME/htdocs/cookery/us/index.html<html><head></head><body><table width="100%" border="2"><tr><th colspan="2">Container: Container</th></tr><tr><td colspan="2"><table width="100%" border="2"><tr><th colspan=2>Header: Header</th><tr><td>Core Branding: Core Branding</td><td>Site Branding: Site Branding</td></tr></table></td></tr><tr><td width="30%">Navigation: Navigation</td><td width="70%">Content</td></tr></table>

17

Using the r3 Command Line Interface

Page 22: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

</body></html>

When displayed in your browser, the file looks like this:

All of the targets currently look same because they all use the same templates, and no translation hasbeen done yet.

Specializing TemplatesYou can make local copies of some of these templates and change them for different products and intls.For this particular example we're going to be moving things around as follows:

Containsintlproduct

contentspecific intl

site branding, navigationgeneric_intlspecific product

(header)specific intl

container, header, core_brandinggeneric_intlgeneric_product

The header is specialized to the generic_product specific intl level for particular intls because corebranding and site branding may be laid out differently for certain intls.

Specializing Completely

To specialize a template for each product/intl combination:

1. Display all the locations searched for a particular target page:

$ r3 template searchpath cookery/us/index.html

0 cookery/us/index.html 1 cookery/us/generic 2 cookery/generic_intl/index.html 3 cookery/generic_intl/generic 4 generic_product/us/index.html 5 generic_product/us/generic 6 generic_product/generic_intl/index.html index.html.ros 7 generic_product/generic_intl/generic

2. To see where a particular template is, from the point of view of a particular target, add it to the r3template searchpath as an optional final argument. In our example, we're looking for the templatecontent.ros:

$ r3 template searchpath cookery/us/index.html content.ros

0 cookery/us/index.html 1 cookery/us/generic 2 cookery/generic_intl/index.html 3 cookery/generic_intl/generic 4 generic_product/us/index.html

18

Using the r3 Command Line Interface

Page 23: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

5 generic_product/us/generic 6 generic_product/generic_intl/index.html content.ros 7 generic_product/generic_intl/generic

3. To specialize a template to the most specific location for its target, use the command r3 templatespecialize. Our example specializes content.ros to level zero:

$ r3 template specialize cookery/us/index.html content.ros 0Template specialized from generic_product/generic_intl/index.html to cookery/us/index.html

0 cookery/us/index.html content.ros 1 cookery/us/generic 2 cookery/generic_intl/index.html 3 cookery/generic_intl/generic 4 generic_product/us/index.html 5 generic_product/us/generic 6 generic_product/generic_intl/index.html content.ros 7 generic_product/generic_intl/generic

Note that this is a copy operation, not a move. The original content.ros still exists at the genericlevel and is still visible to other products and intls. Only cookery/us/index.html can see thiscopy.

4. Now you can edit your copied template and make it very specific to that product. Our example usesvim for editing the template content.ros; you may be using a different tool.

$ vim $R3HOME/templates/cookery/us/index.html/content.ros

• Make the following change:

Content: Cookery in the USA

• Let's assume we've repeated this operation for other products and intls:

$ for product in cookery wine cars> do for intl in us ca fr jp> do r3 template specialize $product/$intl/index.html content.ros 0> vim $R3HOME/templates/$product/$intl/index.html/content.ros> done> done

5. Regenerate the files:

$ r3 generate -agenerating cars/cagenerating cars/frgenerating cars/generic_intlgenerating cars/jpgenerating cars/usgenerating cookery/cagenerating cookery/frgenerating cookery/generic_intlgenerating cookery/jpgenerating cookery/usgenerating generic_product/cagenerating generic_product/frgenerating generic_product/generic_intlgenerating generic_product/jpgenerating generic_product/usgenerating wine/cagenerating wine/frgenerating wine/generic_intl

19

Using the r3 Command Line Interface

Page 24: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

generating wine/jpgenerating wine/us

You should have:

Note that each page picks up its own specialized content.

Specializing for Product, with Generic Intl

r3 enables you to specialize a template for a specific product, but share generic intl data. This means thatall intls within a product can share the same site branding and navigation templates, and translation takescare of the specific intl's requirements for these templates.

Our example project specializes site_branding.ros and navigation.ros.

1. Find the searchpath for site_branding.ros and specialize it to generic_intl:

$ r3 template searchpath cookery/us/index.html site_branding.ros

0 cookery/us/index.html 1 cookery/us/generic 2 cookery/generic_intl/index.html 3 cookery/generic_intl/generic 4 generic_product/us/index.html 5 generic_product/us/generic 6 generic_product/generic_intl/index.html site_branding.ros 7 generic_product/generic_intl/generic

$ r3 template specialize cookery/us/index.html site_branding.ros 2Template specialized from generic_product/generic_intl/index.html to cookery/generic_intl/index.html

0 cookery/us/index.html 1 cookery/us/generic 2 cookery/generic_intl/index.html site_branding.ros

20

Using the r3 Command Line Interface

Page 25: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

3 cookery/generic_intl/generic 4 generic_product/us/index.html 5 generic_product/us/generic 6 generic_product/generic_intl/index.html site_branding.ros 7 generic_product/generic_intl/generic

2. Verify that site_branding.ros is visible to other intls in the cookery product at that location:

$ r3 template searchpath cookery/jp/index.html site_branding.ros

0 cookery/jp/index.html 1 cookery/jp/generic 2 cookery/generic_intl/index.html site_branding.ros 3 cookery/generic_intl/generic 4 generic_product/jp/index.html 5 generic_product/jp/generic 6 generic_product/generic_intl/index.html site_branding.ros 7 generic_product/generic_intl/generic

3. Edit the file as follows:

Cookery Site Branding: <r3:trans>Cookery Site Branding</r3:trans>

4. Repeat the preceding step for the cars product, and also allow wine to inherit its site branding fromcookery. The wine product inherits its site_branding from cookery.

$ r3 template searchpath cars/us/index.html site_branding.ros

0 cars/us/index.html 1 cars/us/generic 2 cars/generic_intl/index.html 3 cars/generic_intl/generic 4 generic_product/us/index.html 5 generic_product/us/generic 6 generic_product/generic_intl/index.html site_branding.ros 7 generic_product/generic_intl/generic

$ r3 template specialize cars/us/index.html site_branding.ros 2Template specialized from generic_product/generic_intl/index.html to cars/generic_intl/index.html

0 cars/us/index.html 1 cars/us/generic 2 cars/generic_intl/index.html site_branding.ros 3 cars/generic_intl/generic 4 generic_product/us/index.html 5 generic_product/us/generic 6 generic_product/generic_intl/index.html site_branding.ros 7 generic_product/generic_intl/generic

5. Then edit the $R3HOME/templates/cars/generic_intl/index.html/site_brand-ing.ros and change it to:

Cars Site Branding: <r3:trans>Cars Site Branding</r3:trans>

6. Repeat the whole process (steps 1 through 5) for navigation.ros, but this time give the wineproduct its own copy.

$ r3 template specialize cookery/us/index.html navigation.ros 2$ vim $R3HOME/templates/cookery/generic_intl/index.html/navigation.ros$ r3 template specialize wine/us/index.html navigation.ros 2

21

Using the r3 Command Line Interface

Page 26: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

$ vim $R3HOME/templates/wine/generic_intl/index.html/navigation.ros$ r3 template specialize cars/us/index.html navigation.ros 2$ vim $R3HOME/templates/cars/generic_intl/index.html/navigation.ros

Specializing for Intl, Retaining Generic Product

Just as you can specialize for a particular product, r3 also enables you to specialize for a particular intlwhile sharing generic product data. Our example assumes that Asian sites, in this case cookery/jp,wine/jp and cars/jp, require core_branding and site_branding to be laid out in right-to-left order, which is controlled by the header.

1. To localize the header to the generic_product/jp level and make the change there:

$ r3 template searchpath cars/jp/index.html header.ros

0 cars/jp/index.html 1 cars/jp/generic 2 cars/generic_intl/index.html 3 cars/generic_intl/generic 4 generic_product/jp/index.html 5 generic_product/jp/generic 6 generic_product/generic_intl/index.htmlheader.ros 7 generic_product/generic_intl/generic

$ r3 template specialize cars/jp/index.html header.ros 4Template specialized from generic_product/generic_intl/index.html to generic_product/jp/index.html

0 cars/jp/index.html 1 cars/jp/generic 2 cars/generic_intl/index.html 3 cars/generic_intl/generic 4 generic_product/jp/index.html header.ros 5 generic_product/jp/generic 6 generic_product/generic_intl/index.htmlheader.ros 7 generic_product/generic_intl/generic

$ vim $R3HOME/templates/generic_product/jp/index.html/header.ros

2. Edit the file:

<table width="100%" border="2"><tr><th colspan=2>Japanese Header: <r3:trans>Japanese Header</r3:trans></th><tr><td><r3:include path="site_branding.ros" /></td><td><r3:include path="core_branding.ros" /></td></tr></table>

3. Generate the files again and review them.

r3 generate -agenerating cars/cagenerating cars/frgenerating cars/generic_intlgenerating cars/jpgenerating cars/usgenerating cookery/cagenerating cookery/frgenerating cookery/generic_intlgenerating cookery/jp

22

Using the r3 Command Line Interface

Page 27: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

generating cookery/usgenerating generic_product/cagenerating generic_product/frgenerating generic_product/generic_intlgenerating generic_product/jpgenerating generic_product/usgenerating wine/cagenerating wine/frgenerating wine/generic_intlgenerating wine/jpgenerating wine/us

Promoting TemplatesThe reverse operation of specialization is called promotion. In r3, you promote templates using the r3promote template command. Using the sample structure we've created so for, suppose you decided tospecialize the navigation template from the French Canadian wine product, but then realized you coulduse it for all Canadian products. That is, suppose you first did this:

$ r3 template specialize wine/ca/index.html navigation.ros 0Template specialised from generic_product/generic_intl/index.html to wine/ca/index.html 0 wine/ca/index.html navigation.ros 1 wine/ca/generic 2 wine/us/index.html 3 wine/us/generic 4 wine/generic_intl/index.html 5 wine/generic_intl/generic 6 cookery/ca/index.html 7 cookery/ca/generic 8 cookery/us/index.html 9 cookery/us/generic 10 cookery/generic_intl/index.html 11 cookery/generic_intl/generic 12 generic_product/ca/index.html 13 generic_product/ca/generic 14 generic_product/us/index.html 15 generic_product/us/generic 16 generic_product/generic_intl/index.html navigation.ros 17 generic_product/generic_intl/generic

To push it back up the inheritance chain, then you might do this:

$ r3 template promote wine/ca/index.html navigation.ros 13Template promoted from wine/ca/index.html to generic_product/ca/generic 0 wine/ca/index.html 1 wine/ca/generic 2 wine/us/index.html 3 wine/us/generic 4 wine/generic_intl/index.html 5 wine/generic_intl/generic 6 cookery/ca/index.html 7 cookery/ca/generic 8 cookery/us/index.html 9 cookery/us/generic 10 cookery/generic_intl/index.html 11 cookery/generic_intl/generic 12 generic_product/ca/index.html 13 generic_product/ca/generic navigation.ros 14 generic_product/us/index.html 15 generic_product/us/generic 16 generic_product/generic_intl/index.html navigation.ros 17 generic_product/generic_intl/generic

23

Using the r3 Command Line Interface

Page 28: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Unlike the template specialize command, the template promote command is a move operation.

Working With Translationsr3 enables you to easily internationalize your web pages. Translations are performed from the commandline or via the GUI. Translation terms are looked up in a search path, just as templates are. And as withtemplates, r3 uses the first encountered match.

1. View all current translated and untranslated strings using r3 translation list:

$ r3 translation listcars/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]

24

Using the r3 Command Line Interface

Page 29: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

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]

25

Using the r3 Command Line Interface

Page 30: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

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 Navigationgeneric_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 Navigationgeneric_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 Navigationgeneric_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 Navigationwine/ca Cars Navigation: Cars Navigation [i] Cars Site Branding: Cars Site Branding [i] Container: Container [i]

26

Using the r3 Command Line Interface

Page 31: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

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 in-herited from a more generic location.

2. You can perform translation from the r3 CLI using r3 translation set for individual terms. Howevera more common approach would be to save the translations for a particular site, or all sites, as anXLIFF file and to send that file to a third party translator. Use the command r3 translation save tosave all translations. For example:

27

Using the r3 Command Line Interface

Page 32: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

$ r3 translation save all alltrans.xmlall 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>

28

Using the r3 Command Line Interface

Page 33: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Exporting and Importing TranslationsLooking at alltrans.xml, you can see that many of the translations are at different inherited genericlevels—the original attribute of the file tag denotes the location of the translation. In the course ofdeveloping this project we ran a generate for all targets including the generic ones that caused sometranslations 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 desiredtarget, remembering to generate parents first.

• Export each site's dictionary separately, enabling inheritance, and then merge the results back in.

1. To export a dictionary separately, use r3 translation save inherited. For example, saves gener-ic_product/fr's dictionary to the file fr.xml. Looking at fr.xml:

$ r3 translation save inherited generic_product/fr fr.xmlgeneric_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 allat 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>

29

Using the r3 Command Line Interface

Page 34: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

</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>

2. Edit the translation XML file, and put in your translations for each term. In our example each termhas simply been wrapped in square brackets with the token fr, so "Wine Navigation" becomes "[frWine Navigation]" etc.

3. Merge the translations you did in the previous step into the dictionary:

$ r3 translation merge fr.xmldictionary data merged from file 'fr.xml'

The above merge operation is actually quite subtle. For every source value, r3 searches the inheritancechain 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 foundsource differs, then r3 inserts the record into the dictionary at the declared location (gener-ic_product/fr in this case).

4. Look at the entire dictionary again. You can see that those translations have become available for allfr and ca sites.

$ r3 translation listcars/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]

30

Using the r3 Command Line Interface

Page 35: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

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]

31

Using the r3 Command Line Interface

Page 36: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

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 Navigationgeneric_product/jp Cars Navigation: Cars Navigation Cars Site Branding: Cars Site Branding Container: Container

32

Using the r3 Command Line Interface

Page 37: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

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 Navigationgeneric_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 Navigationwine/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]

33

Using the r3 Command Line Interface

Page 38: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

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]

5. Repeat the process for the other intls, always exporting the generic_product/$intl locationto $intl.xml, replacing the translations in that file, and merging them back. For ca make only atoken translation of the "Cars Site Branding" and leave the rest of the translations alone.

6. Then generate all the files again and examine the results.

$ r3 generate -a

Your final results should look something like this:

34

Using the r3 Command Line Interface

Page 39: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

35

Using the r3 Command Line Interface

Page 40: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

36

Using the r3 Command Line Interface

Page 41: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Chapter 5. Using the r3 GUIThe r3 GUI simplifies some of the more tedious project setup steps, such as creating dimensions and addingwords or strings for translation. Note, however, that this version of the r3 GUI does not yet have full paritywith the CLI. Moving and copying of templates and managing inheritance must still be done from thecommand line.

This chapter is organized by GUI tab and describes the features for that tab.

Dimensions TabThe dimensions tab enables you to create products and intls.

Figure 5.1. Dimensions Tab

To create a dimension, select the type of dimension you want to create, enter a name for your dimensionin the name field, and click add.

To delete a dimension, select the dimension type to list all the current products or intls, and click deletenext to the dimension you want to delete.

Targets TabYou can use the targets tab to create and delete targets, and to view searchpath and template informationassociated with it.

To add a target, set location to the product and intl you are creating the target for, and click change. Enterthe name of the target in the name field, and click add. A message appears in red when the target has beensuccessfully created.

Note

If you change the product and/or intl but do not click change, the new target is created forthe product and intl that was displayed before you changed it.

37

Page 42: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Figure 5.2. Targets Tab

Clicking info displays information about a target, including its location, template name, and searchpaths.

Figure 5.3. Displaying Information about a Target

Translations TabThe translations tab lets you easily add, search for, translation text, and manage translation inheritance.

Adding TranslationsTo add a translation:

1. In location, set the product and intl for the translation, and click change.

2. In add translation, enter the source text and its translation, and click add. A red message tells youthat your text has been added to the translation and its searchpath location.

38

Using the r3 GUI

Page 43: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Figure 5.4. Adding a Translation

Searching For TranslationsYou can search for translations by source text or by translation text by entering the search term, choosingthe appropriate search option, and clicking search. r3 responds with the location of the translation, andthe manage translations view displays the term and its source or translation. The default search behavioris a fuzzy search. To enforce a strict match, select exact. Also note that you can filter your searches ontranslation status, approved vs. unapproved. (When you change a translation, r3 automatically sets it toapproved. You can later filter out approved translations and concentrate on those that still need work.)

Figure 5.5. Searching for a Term

Managing TranslationsThe manage translations view displays translation text for a specific product and intl in groupings of 10.You can edit the translation text within this view and click update to save the changes.

39

Using the r3 GUI

Page 44: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

Figure 5.6. Managing Translations

If you set an inheritance path for translations, the path displays when you click show to display translationinformation. You can delete a translation by clicking delete. The show view also enables you to move thetranslation inheritance to a different location in the searchpath.

Figure 5.7. Managing Translation Inheritance

In the example above, fromage has been added to the translations in the searchpath cookery/fr/gen-eric. By clicking move you can copy fromage to the translations in the searchpath cookery/us/gen-eric (it appears in both searchpaths).

Note

The translation rule is: "Copy on specialize, move on promote." If you're specializing downfrom a generic context removing the original translation (in our case, the translation in

40

Using the r3 GUI

Page 45: r3 User Guide - Yahoo Developer Network · Template files have an .ros extension. They are specialized to "container le vel" (generic to the intl). The def ault template name is tak

cookery/us/generic) would delete it for any dimensions inheriting from it. However,when you promote a translation up the searchpath you should remove the current instance.

Generate TabThe generate tab enables you to easily generate dimensions and targets. You simply select the productand intl you want to generate, or select all to generate all products and intls, and click generate.

Figure 5.8. Generate Tab

A list of the generated files displays in a new window.

Figure 5.9. Generating Files

41

Using the r3 GUI