DriveWorks Pro 24

Localization

Localization

Localization is a feature within DriveWorks Pro Server Groups designed to allow DriveWorks implementations to be localized into multiple languages.

Localization data is managed through the DriveWorks Pro Server web application, and can be accessed within DriveWorks projects by using Localization Functions within Rules.

This is also used throughout DriveWorks CPQ Sales Portal, which currently ships in en-US, however modifying the CPQ and CPQ_Sales_Portal, either by changing the Base Locale Values or adding new Supported Locales will change the values displayed to CPQ Users.

Recommendations

Before implementing localizations we recommend the following:

• Localization is only available for Shared Groups.

  The Shared Group must be open and logged in on DriveWorks Pro Server for the necessary securable features to be visible when creating Roles in Security Settings (in DriveWorks Administrator).

• The logged in user must belong to a team that has a role with the following permissions applied:

  See Add Role in DriveWorks Administrator - Security Settings for more information.

  Target	Action	Scope
  Locale	Create	Team
  Locale	Update	Team
  Locale	Delete	Team
  Localization Package	Create	Team
  Localization Package	Read	Team
  Localization Package	Update	Team
  Localization Package	Delete	Team
  Localization Package	See	Anywhere Assigning the Anywhere scope to this action allows a package to be seen on the Localization page when no team has been assigned in the Grant Ownership to Team option when the package was created. See Creating A Package.

In this topic

Packages

Any Packages the current user has permission to see will be displayed within the Localization Page in DriveWorks Pro Server, alongside their Base Locale, and any other Locales supported by the Package.

By selecting a Locale from the drop down you can also highlight any Packages within the group supporting this Locale.

A selected Package can also be deleted from the Group here.

1. Select the package from the list.
2. Click the Delete button.
3. Select Yes on the confirmation dialog.

Creating A Package

From the main Localization page:

1. Click the Create Package button.
2. In the Create Localization Package dialog enter a Reference Name
3. Optionally select a Base Locale.
4. Optionally select a Team from the Grant Ownership to Team field.

   This will typically be the team that has Localization Package permissions.

   When no team is selected the package will not be visible in the list unless Anywhere scope has been applied to the See action in the permission for the role applied to the team.

   See Recommendations above.

5. Click Create.

Viewing A Package

Click the Package Reference Name or the View button in the Packages page, to see the contents of a package.

This will display the following:

• Resource Key Identifier
• Base Locale Value
• Localized Value

  If a Package has no Supported Locales, this column will not be displayed.

• Comments

The Supported Locale can be changed in dropdown below the Reference Name.

Copy buttons allow the Package Reference Name and Resource Key Identifiers to be copied to the clipboard.

This is useful when consuming the Package within a DriveWorks implementation.

Modifying A Package

Localization Packages can be modified by permitted users within the Package Page by clicking the Edit button.

When a Package is being edited, the selected Supported Locale cannot be changed until either the changes are saved or cancelled.

Renaming A Package

1. Click the Edit button next to the Localization Package Reference Name.

   

2. Enter the new name for the Package.

   

   An invalid name will display a warning.

   

   This must be corrected before proceeding.

3. Click Apply.

Updating Resource Values

To clear a Base Locale Value or Localized Value:

1. Select the value from the list.
2. Click the Clear button.

   

   When a Localized Value is (empty) the Base Value will be used as a fallback when getting the Localized data.

To enter a Value that spans multiple lines.

1. Select the value from the list.
2. Enter the value to appear on the first line.
3. For each subsequent new line press shift + enter

   

   The input will expand to accommodate the additional lines, and collapse back once the change is submitted.

   Values that do not fit within the collapsed view, will be shown with an ellipsis (...), for example:

   

Adding Resource Keys

To add a new Resource Key:

1. Click the Add Key button.

   A new row will be inserted into the Resource Key package.

   The input focus will immediately change to the new Key's Identifier input.

   

2. Enter a value for the Identifier.

   The Identifier value:

   • Cannot begin with a number
   • Cannot contain a space
   • Cannot be empty
   • Cannot match an existing Identifier value.

Deleting Resource Keys

To delete a Resource Key:

1. Select one or more rows to be deleted from the Package page.
2. Click the Delete Key button.

   

   This will mark the key for deletion, it will be deleted once changes are saved.

3. Click the Save Changes button.

Saving changes

When the Package has been modified, the Save Changes button will become enabled.

This will also show the total number of modifications made to the Package, and will change color if there are any errors in the modified data.

To revert the current modifications, click the Cancel button.

If there are modifications to be reverted, the following dialog will be displayed.

Alternatively, click the Revert Changes button within the Save Changes dialog.

Within the Save Changes dialog all of the changes will be displayed individually, alongside the type of modification that has occurred.

Each row can also be expanded to show more information about the Resource Key that has been modified.

Package Errors will also be shown, alongside the reason for the error.

The changes cannot be saved until these issues are resolved.

Update Reactivity

For performance reasons, Localized Data within DriveWorks Specifications and the CPQ Sales Portal will not update immediately, unless DriveWorks Pro Server is restarted.

Changes may take up to 30 minutes to be reflected.

Import/Export XLIFF

XLIFF is common file format used for localization, and is supported by many localization and machine translation tools.

This allows DriveWorks Localization Packages to be Localized in third party localization tools or by localization services, rather than manually editing the localized values within DriveWorks Pro Server.

DriveWorks uses the XLIFF 2.0 Standard.

This is not designed as a way to backup or transfer packages.

Exporting

Multiple Packages sharing the same Base Locale can be exported simultaneously for a given Target Locale.

XLIFF Files are always exported with the Source Language set to the Base Locale of the Package.

If a Package already supports the Target Locale, the Localized Values for this Locale will also be included in the export.

Any Resource Key comments will be included in the exported file as a note, this can be helpful when working with third party localization providers to describe the purpose of a key, or format strings within the source value.

Importing

Once an exported XLIFF file has been localized, it can be imported back into DriveWorks Pro Server to update the Localization Packages.

Importing cannot create new Packages or Locales within the Group, or new Resource Keys within a Package.

Modifications to the Source Language or notes within the XLIFF file will not be imported.

Any warnings with the XLIFF file will be displayed.

(Note image shown captured in dark mode.)

Certain warnings are recoverable, such as a key being renamed or missing (this may happen if Resource Keys or Packages have been added or renamed since the file was exported).

Other issues are treated as errors, these must be corrected before proceeding.

(Note image shown captured in dark mode.)

Errors could include Resource Key or Localization Package not being recognized (this may happen if Resource Keys or Packages have been deleted since the file was exported).

This is designed to help prevent data loss.

Locales

Managing Locales Within A Group

Group locales are administered from the Localization page.

Viewing Locales

From the Localization page:

1. Click Manage Group Locales.

   

2. This displays all Locales in the group.

   

   From here group locales can be:

   • Added
   • Edited
   • Deleted

Adding Locales

From the Manage Group Locales dialog:

1. Click the Add Locale button.
2. Enter the Locale Tag in the Locale Tag field.

   

3. Click the Save button.

Editing Locales

From the Manage Group Locales dialog:

1. Select the locale to be modified
2. Click the Edit button.
3. Make the change to the Locale Tag field in the Edit Locale dialog.

   Modifications to the locale tag are displayed in the corresponding sub-tag field giving a visual feedback before the changes are committed.

   

4. Click Save Changes.

Deleting Locales

Deleting a Locale will delete it from the group entirely.

From the Manage Group Locales dialog:

1. Select the locale to be deleted.
2. Click the Delete button.

   When a locale is deleted from a group, all Localized Resources for the Locale will also be deleted.

3. A list of affected Packages is displayed in the Delete Locale from Group confirmation dialog.

   

   Click Yes to confirm deletion.

Managing Locales Within A Package

Locales applied to a Package are administered from the Package page.

Viewing Locales

From the Packages page:

1. Click Manage Package Locales.

   

2. The Manage Package Locales dialog shows all locales currently supported by the Package.

   

   This indicates the current Base Locale.

3. Click Close to return to the Packages page.

Adding Locales To A Package

From the Manage Package Locales Dialog:

1. Click the Add Locale to Package button.
2. Select Existing or New
   • Existing

     Select the existing locale tag from the Locale field.

     

   • New

     Enter the new locale tag in the Locale Tag field.

     See Adding Locales for more information about Locale Tags and the editor.

     

3. Click Save.

Change Base Locale

This is useful when localizing CPQ for instance, when updated packages in a locale other than en-US are exported as XLIFF files based on this updated data.

As the base is used as the fallback for any missing values within supported locales, ensure the base locale has been completely localized.

From the Manage Package Locales Dialog:

1. Select a locale (that is not currently the base locale).
2. Click Set as base.

   This displays a confirmation dialog where the Current Base and the New Base that will be applied.

3. Click Yes in the Set Base Locale confirmation dialog.

   

Removing Locales

Removing a Locale will remove it from the package only.

From the Manage Package Locales Dialog:

1. Select the locale to be removed.
2. Click the Remove button.
3. Click Yes in the Remove Locale from Package confirmation dialog.

   

Locale Tags

When creating locales the following should be observed.

Locale Matching

When selecting the supported locale to use, DriveWorks uses Distance-Based locale matching, based on the CLDR language/script/region distance data.

For example:

{
    "Desired": {
        "LanguageTag": "ca"
    },
    "Supported": {
        "LanguageTag": "es"
    },
    "Distance": 20,
    "IsOneWay": true
},

This determines that ca (Catalan) has a distance of 20 to es (Spanish), compared to the standard distance of 50.

So if a user has their machine set to ca it will try to access a Package supporting es and en-ES (base), it will prefer es.

This is only one way, meaning if a user with their machine set to es tries to access a Package supporting ca and en-ES (base), it would prefer the Base Locale.

Prior to this distance match, DriveWorks will canonicalize the locales supported by the Package and in the user's Accept-Language request header (Current Client Languages special variable).

This is designed to ensure equivalent Locales are treated the same as one another in the matching process.

For example en is equivalent to en-Latn-US, as defined by the LikelySubtags in the CLDR, and eng is equivalent to en as defined by LanguageAliases.

This also means that if these equivalent Locales exist within a group that is supported by a package, there is no defined logic for which should take precedence.

DriveWorks also supports "quality values" in the clients Accept-Language header to influence the distance matching.

For example, the client could have the header:

fr-CH, en;q=0.8, fr;q=0.6

This means Swiss French takes precedence, but English is weighted higher than other French Locales.

If no quality values are set, the order of precedence is influenced by which value occurs first.

The user typically wouldn't set this manually, but is managed through their browser/OS language settings.

For example the Languages set below in Microsoft Edge resulted in the Accept-Header:

en-GB,en-US;q=0.9,en;q=0.8,es-MX;q=0.7,es;q=0.6.

When running a specification through DriveWorks Administrator, the Accept-Header used will typically just be the Windows Languages, in order, with no quality.

The example below will return:

en-US,en-GB.

A slimmed down version of the CLDR is supplied with DriveWorks, and compiled for faster usage in Locale Matching.

It is unlikely this will change drastically enough to require modifying.

However it can be overwritten by placing the CLDR archive, entitled cldr.zip located in

C:\Users\<USER>\AppData\Local\DriveWorks\Cldr

(on the machine DriveWorks Pro Server is installed)

This will be read on startup and converted into a cache.jsonfile.

The cache file will be loaded instead of the CLDR archive unless it is deleted.

The archive should have the structure:

• cldr.zip
  • common
    • supplemental
      • languageinfo.xml
      • likelySubtags.xml
      • supplementalData.xml
      • supplementalMetadata.xml

Permissions

Package Permissions

Localization Packages have five Permission action types:

• Create - Create new Localization Packages
• See - See the Package and it's supported Locales within the Packages list
• Read - See permission + the ability to read the contents of the Package
• Update - Edit the contents of a Localization Package, add/remove Resource Keys, add/remove Supported Locales, Set Base Locale, Rename the Package
• Delete - Delete a Localization Package and all of its resources

These Permissions respect Scope, which evaluates whether the Localization Package is “owned“ by the given Team, or its parents

Locale Permissions

Locales have three Permission action types:

• Create - Create new Locales
• Update - Edit the Locale Tags of a Locale
• Delete - Delete a Locale, and any Localized Resources in Packages supporting the Locale. This should be carefully allocated, given the wide scope of potential changes.

Locales can be read by any user, as they are not treated as sensitive data.

Scope should not impact these permissions, as Locales cannot be owned.

Managing Ownership

Ownership can either be granted to a Team when the Package is created (this only requires the Create permission), or through the Manage Ownership dialog in the Package Page (this requires Administer Group Security, rather than a Package Permission).

DriveWorks Functions

The following DriveWorks functions will be included in Projects within DriveWorks Pro Server Shared Groups:

• GetLocalizationPackages
• GetLocalizationPackage
• GetLocalizedResource
• GetLocalizedResourceByLocale

GetLocalizationPackages

Returns a Table containing the Localization Packages the user has permission to See, and their supported Locales as a pipe-separated list.

Syntax

GetLocalizationPackages()

Example

Example Outcome

The result will be returned as an array, which will look like:

{"Localization Package","Supported Locales";"CPQ","en-US|es-ES"}

When viewed as a table:

GetLocalizationPackage

Returns a Table containing the Resource Key Identifiers in the Package, and their corresponding Localized Value in the matched Locale. This will include fallbacks to the Base Locale wherever a value is empty in the matched Locale.

Syntax

GetLocalizationPackage(Package Name, [Locales])

Where:

Package Name - is the Reference Name of the Package to retrieve

Locales (optional) - is a comma separated Language-Accept header to match against when retrieving the localized data.

If no Locales are specified, the Current Client Languages value will be used.

Example

Example Outcome

The result will be returned as an array, which will look like:

{"Identifier","Localized Value";"QuoteCommentRevision.QuoteComment.TooltipText","","AccountPrimaryContact.Account.DisplayName","Account"}

When viewed as a table:

GetLocalizedResource

Returns the Localized Value of the matching Resource for the matching Locale, based on the Current Client Language value.

Fallbacks to values in the Base Locale of the Package take precedence over the Fallback value specified here.

Syntax

GetLocalizedResource(Package Name, Resource Identifier, [Fallback Value])

Where:

Package Name - is the Reference Name of the Package to retrieve the resource from.

Resource Identifier - The Resource Key Identifier of the resource to retrieve

Fallback Value (optional)- If the Package or Resource Key cannot be found in the group, or the value is un-set, this value will be returned. If no fallback is specified, an error will be returned.

Example

Example Outcome

The image below is an extract from the Dimensions package, showing the Identifier Width.Label

For a machine where the current client language value is en-US the example will return:

Width

For a machine where the current client language value is de-DE the example will return:

Breite

GetLocalizedResourceByLocale

Returns the Localized Value of the matching Resource for the matching Locale, based on the supplied Locales value

Syntax

GetLocalizedResourceByLocale(Package Name, Resource Identifier, Locales, [Fallback Value])

Where:

Package Name - The Reference Name of the Package to retrieve the resource from

Resource Identifier - The Resource Key Identifier of the resource to retrieve

Locales - A comma separated Language-Accept header to match against when retrieving the localized resource

Fallback Value (optional) - If the Package or Resource Key cannot be found in the group, or the value is un-set, this value will be returned. If no fallback is specified, an error will be returned.

Example

Example Outcome

For a machine where the current client language value is en-US the example will return:

Width

For a machine where the current client language value is de-DE the example will return:

Breite

Integration With Business Objects

This applies to Package Modifiers.

When a Business Object Package has a Reference Name matching a Localization Package, they are treated as related, and an indicator will appear allowing navigation between the Business Object Package and the Localization Package.

If a Business Object Package does not have a corresponding Localization Package, it will present an option to generate a new one. This will generate all of the required Resource Keys to Localize the object.

A Base Locale can be set for the new Package, and this then allows the DisplayName Values to be pre-populated based on the Business Object Package Reference Names.

Package Updates

When a Package is updated, for example adding new Attributes to a Business Object using a Package Modifier, the Business Object indicator will show a warning of any keys missing from the package.

Clicking this will show the missing keys, and give the option to add them to the Package.

If a Required Value is empty, the indicator will display Missing Values.