(Deprecated) Localizing Guides

Localize assets
Localize the Guide runtime
Localize the data model

* New for 10 *

Guides include strings that you can localize, such as captions, Help text, and list sources.

When a Guide filler accesses a localized Guide, the server displays the Guide based on their locale. The Guide runtime determines the locale from the HTTP headers that the browser submits.

The process that renders the Guide must accept the locales as an input variable and pass the value as an input to the Generate Guide operation. For information about the Generate Guide operation, see (Deprecated) Generate Guide operation.

To localize the Guide strings, export the translation resources from Workbench. Workbench creates an XLF file in the application that the Guide resides in. The XLF file includes only the strings that are defined in the Guide properties. It does not include strings from the data model that the Guide is based on.

After you localize the Guide resources, preview and test the Guide for each locale. In the Guide Properties view, specify the preview language in the Preview Settings.

Localize a Guide

In the Applications view, create a folder named Locales in your application.
Create a subfolder for each locale, such as en_US or fr_FR. For example, /<Application Name>/1.0/Locales/fr_FR/.
In the Applications view, right-click the Guide, and then select Export Translation Resources. Workbench creates an XLF file named <Guide name>.<locale>.xlf in the same folder as the Guide.
After the XLF files are translated, in the Guide Tree view, select the Guide.
In the Guide Properties view, from the Preview Settings, select the locale.
Click Preview.

XLF files

Use multiple XLF files that contain one language translation per file. The XLF filename ends with the language tag, such as <GuideName>.fr.xlf. The target language is an attribute of the file element:

<file original="/server/MyApp/1.0/MyGuide.guide$MyGuide_GuideExperience.xml" source-language="en" target-language="fr-fr" tool="GuideBuilder"> 
  <body> 
    <trans-unit id="99999" resname="99999" restype="caption"> 
      <source>Text for translation.</source> 
      <target>Texte pour traduction.</target> 
</trans-unit>

Images are referenced in the <source> tag. If the source contains text for translation, include the image reference in the <target> strings. You may need to manually copy the image references to the <target> strings.

Localize assets

Guides can include assets that you can localize, such as images and videos. When you preview or render a Guide, the server determines the locale from the HTTP headers that the browser submits.

Workbench uses the following folder structure to find assets that best match the requested locale: \<application name>\<application version number>\Locales\<locale>\<location of asset files>\.

For example, if the assets are located in the \my_application\1.0\assets\images\ folder, copy the French assets to the \my_application\1.0\Locales\fr_FR\assets\images\ folder.

In Workbench, copy the localized assets into the appropriate locale folders.
In the Guide Tree view, select the Guide.
Preview the Guide with the localized assets. In the Guide Properties view, from the Preview Settings, select the locale for the assets, and then click Preview.

Localize the Guide runtime

Workbench includes resource bundles of the Guide runtime for English (en_US), French (fr_FR), German (de_DE), and Japanese (ja_JP) locales. The default locale is English (en_US).

The Guide runtime strings that are localized include Add, Copy, Remove, Next, Back, and Submit buttons. The strings are localized in resource bundles named guides_rb.swf. There is a resource bundle file in each \Guides (system)\2.0\Locales\<locale>\Runtime application folder.

To create resource bundles for additional locales, use the properties file located in the Guides \SDK\code\libs\runtime\locales\<locale>\ folders.

The Guides SDK is available in the Adobe LiveCycle ES4\Workbench 11\sdk\misc\Guides folder where Workbench is installed (by default C:\Program Files\Adobe LiveCycle ES4\Workbench 11\sdk\misc\Guides).

The properties files include the key and the value for each string in the Guide runtime. When you create a properties file, edit the values, but do not change the keys.

Use the MXML compiler to compile the properties files into SWF files.

Copy the GuidesRuntime.properties and the XFAModel.properties files.
Open the properties files with a text editor, and then edit the values for each string.
On the machine where Workbench is installed, ensure that the latest Java Runtime Environment (JRE) is installed.
Click Start > Programs > Accessories > Command Prompt.
Navigate to the Flex_SDK\bin folder in the Workbench install location. By default, the path is C:\Program Files\Adobe LiveCycle ES4\Workbench 11\Flex_SDK.
Type the mxml command, and specify the following arguments:
- -locale: Specify the new locale that you are creating, and a fallback locale to use if the new locale is not found.
- -source-path: Specify where the property files are located.
- -include-resource-bundles: Specify the following GuidesRuntime, XFAModel, and Flex SDK resource bundles:
  
  GuidesRuntime,XFAModel,aircontrols,charts,collections,components,containers,controls,core,effects,fiber,formatters,layout,logging,messaging,rpc,SharedResources,skins,sparkEffects,states,styles,textLayout,utils,validators
- -output: Specify where you want the location and filename for the compiled resource bundle. Name the Guides runtime resource bundle file guides_rb.swf.
  
  The following example creates an it_IT resource bundle:
```
mxmlc -locale=it_IT,en_US 
-source-path="C:\Users\user_name\Workbench 11\server_name\application_name\1.0\locale\it_IT" 
-include-resource-bundles=GuidesRuntime,XFAModel,aircontrols,charts,collections,components,containers,controls,core,effects,fiber,formatters,layout,logging,messaging,rpc,SharedResources,skins,sparkEffects,states,styles,textLayout,utils,validators 
-output="C:\Users\user_name\Workbench 11\server_name\application_name\1.0\bin\it_IT\Runtime\guides_rb.swf
```
Copy the new \<locale>\Runtime\guides_rb.swf into the \Guides (system)\2.0\Locales folder.
Exit Workbench, and then restart it and login. Workbench caches the locales to improve performance.
Preview the runtime strings, using the locale that you created. In the Guide Properties view, from the Preview Settings, select the locale, and then click Preview.

Localize the data model

The data model that a Guide is based on can include strings, styles, and validation messages that you can localize.

Localizing an XDP form

If the Guide is based on an XDP form, the best practice is to override the strings using the Guide Properties view.

If you cannot override the XDP form strings, create an XDP form for each locale, and then create a Guide for each XDP form. For example, if the XDP form includes validation messages that you need to localize, create an XDP form and a corresponding Guide for each locale.

For information about localizing XDP forms, see Using XLIFF for translating Adobe LiveCycle Designer ES form designs.

Localizing an data model (FML)

If the Guide is based on an data model (FML), localize the strings in the Modeler. Define the strings in styles, and then create a resource bundle for each locale.

For more information about localizing an data model (FML), see Model XML elements reference.

In the model, use styles to define localizable strings.

<style name="bid_amount"> 
    <message name="caption" bundle="AuctionModelProperties" key="bid_amount_caption"/> 
    <message name="description" bundle="AuctionModelProperties" key="bid_amount_description"/> 
    <message name="error" bundle="AuctionModelProperties" key="bid_amount_error"/> 
</style>

Create a properties file to hold the strings. For example, \locale\en_US\AuctionModelStrings.properties.

bid_amount_caption=Amount of Bid 
bid_amount_description=The amount that you'd like to bid.  The minimum bid is 10000. 
bid_amount_error=Invalid Bid

Create localized versions of the properties files and add them to the corresponding locale folders. For example, \locale\ja_JP\AuctionModelStrings.properties.

For each locale, compile the properties file into a SWF file. For information, see Using Resource Modules in Using Flex 4.5.

Wichtig: The SWF filename must be the same as the FML filename, with an _rb suffix. For example, if the FML model name is AuctionModel.fml, the SWF filename must be AuctionModel_rb.swf.

mxmlc -locale=en_US -source-path=locale/{locale} -include-resource-bundles=AuctionModelStrings,core,effects,skins,styles -output Locales/en_US/Models/AuctionModel_rb.swf 
mxmlc -locale=ja_JP -source-path=locale/{locale} -include-resource-bundles=AuctionModelStrings,core,effects,skins,styles -output Locales/ja_JP/Models/AuctionModel_rb.swf

In Workbench, add each SWF file to the appropriate locale folder. For example, /<Application Name>/1.0/Locales/fr_FR/models/AuctionModel_rb.swf.

The location of the <model_name>_rb.swf file must mirror the location of the model. For example, if the model is /MyApplication/1.0/myModels/AuctionModel.fml, the <model_name>_rb.swf file must be /MyApplication/1.0/Locales/<locale>/myModels/AuctionModel_rb.swf.

If there is no corresponding /Locales/<locale>/../<model name>_rb.swf for the specified preview locale, the preview uses the default _rb.swf file. The default _rb.swf file is located in the same folder as the data model (FML). If there is no default _rb.swf file, the preview uses default strings. As a best practice, either create a default _rb.swf file or, in the FML model, specify default strings in the text attribute of the style element:
```
<style name="bid_type"> 
  <message name="caption" text="Default bid_type caption text" bundle="AuctionModelStrings" key="bid_type_caption"/> 
  <message name="description" text="default bid_type description text" bundle="AuctionModelStrings" key="bid_type_description"/> 
</style>
```