Localization with an XLIFF Package

The XML Localization Interchange File Format (XLIFF) is a standardized document used for localization.

Tip: XLIFF packages are useful for the localization of small publications and for projects that can be completed by one translator.

Package Contents

An XLIFF package can contain the following resources:

Note: Only translatable elements are included in the package. Attribute values are not included, and elements with the translate attribute set to no are not included in the packages.
XLF File
A file that contains all the DITA content to be localized for a particular project. The name of the file indicates the target language, for example, pl=Polish and fr-ca=Canadian French. Depending on how many locales, that is target languages, you select when creating your XLIFF pPackage, it can contain one or more XLF files.
Note: The package contains complete text content from the dependencies of the map, including resource-only topics. In other words, the content added with content references (conref) or content key references (conkeyref) is localized.
Important: The localization provider should never modify the content of source elements inside the XLF file. Instead they should modify the content of target elements to provide their localization.

Also, they should never modify the name of the XLF file. If they modify either source elements or the XLF file name, when loading the XLIFF Package back to Heretto CCMS, Heretto CCMS will show errors since it no longer is able to link the source text with the target text content correctly.

Project Notes
Notes that you add when you create a localization job. Project notes are useful to share information with the localization provider.
Remember: Always ask the localization provider to read the project-notes.txt file included in the package. Otherwise, they may ignore it.

Localize Content with an XLIFF Package

XLIFF packages contain only textual content.

Tip: If you want to localize both the textual content and media content, you can use an XLIFF package and a media package. Consider using a source package for localization.
  • Set the source language for the DITA content that you want to localize.
  • Recommended: Publish the reference content.
    Remember: While publishing, set the locale option to the source language.
This process covers both the textual localization with the use of an XLIFF package and the optional media localization with the use of a media package.
Create and localize packages
  1. Create an XLIFF Package.
  2. If the map that you want to localize contains any media that needs to be localized, create a media package. See Create a Media Package.
  3. Do any of the following:
Upload the localized packages to Heretto CCMS
  1. Upload the localized XLIFF package to Heretto CCMS. See Upload the Localized XLIFF Package
  2. If applicable, upload the localized media package to Heretto CCMS. See Upload the Localized XLIFF Package.
Verify and publish the localized content
  1. Optional: Preview the localized content. See View Localized Content.
  2. Publish the localized content.
    Remember: While publishing, set the Locales option to a desired target language.
If needed, do any of the following:

Create an XLIFF Package

Create an XLIFF package for a map that includes one XLF file with all your content for that map. Only one XLF life is created for each localization job, regardless of how many files are included in your map. The XLIFF package contains no media files, so if your map contains media files that require localization, make sure to create a Media Package for your map and send it to the localization provider.
  1. In the content library, click the map you want to localize.

    On the right side of the screen, the Resource Details Drawer appears.

  2. Create a localization package for a map by doing on of the following:
    OptionDescription

    Recommended: Create a localization package for a released map

    1. In the Resource Details Drawer, select Releases .

    2. In the Releases tab, go to the release you want to localize and click Localize.

    Create a localization package for a branched map

    1. In the Resource Details Drawer, select Branches. You will see the list of branches related to your map.

    2. In the Branching tab, switch to the branch that contains the map you want to localize.

    3. The Branching tab closes and you are back in the content library. Click the map for which you want to localize content.

    4. In the Resource Details Drawer on the right of the screen, select the Jobs Tab.

    Create a localization package for a standard map

    In the Resource Details Drawer, select the Jobs Tab.

  3. Click the Create Localization Job Button.
  4. Configure the XLIFF localization package by completing the following steps:
    1. From the Job Type drop-down menu, select XLIFF Package.
    2. In the Manager drop-down menu, leave your email address or change it to a different person. As a result, your localization provider will have this information in the project-notes.txt file in the XLIFF package.
    3. Click the Locales field, and pick as many languages as you want.
    4. Click the Due Date field and select the date when you want the action to be completed.
    5. In the Notes field, enter information about the project, including information for the localization provider. This information will be added to the XLIFF package in the project-notes.txt file.
    XLIFF localization job
  5. Click the Create Button.
  6. In the Jobs tab, click the newly created package.
  7. Click Download Localization Package and save the ZIP package to your computer.
    A ZIP file named companypackage type-localization-job-number.zip, for example herettoxliffpackage-localization-job-101.zip, is saved to your computer. The ZIP file contains the following elements:
    xliff package content
    where:
    • localization-reference-pdf folder contains the reference PDF

    • pl-_-.xlf is the XLF file to which content in the target language will be added in the target elements

    • project-notes.txt contains project notes added as part of this localization job 

  8. Complete one of the following actions:
    • If no media files, for example, diagrams or screenshots, associated with your map require localization, send the ZIP file to your localization provider.
    • If media files associated with your map require localization, complete Localize Content with a Media Package and .

Localize XLIFF Package Content

If needed, you can localize content in-house instead of sending it to an external localization provider.

  1. Save the ZIP file you received for localization to your computer and unzip it.
    Important: Do not change the name of the folder to which you unzip the file.
  2. Open the unzipped XLIFF folder and read the project-notes.txt file
    The project-notes.txt file contains an email address of the project manager and important project-related information.
  3. Open the XLF file, for example pl-_-.xlf, and localize content that is in the target elements.
    Important: Do not modify any content outside of the <target/> elements.
    Tip: You can use free editors to open and edit XLIFF packages.
  4. When you finish localizing content, save the XLF file to the original unzipped folder under the original file names and extensions.
  5. Zip the localized XLIFF package by right-clicking it and compressing it to a ZIP file.
    Important: The new ZIP file must be named exactly the same as the original ZIP file.
  6. Send the localized ZIP file back to the project manager or upload it to Heretto CCMS.

Upload the Localized XLIFF Package

Upload the XLIFF file containing the localized target elements. When your localization provider has localized your content, they send you an identical XLIFF ZIP file with the same content. The only difference is that the target elements of the XLF file now contain localized content. Load the ZIP file to Heretto CCMS and verify the localization.
Important: Do not rename the XLF file or the XLIFF ZIP files of localized content.  Heretto CCMS associates localization packages with localization jobs. Both file names must remain the same as the original file names of the localization job you created for Heretto CCMS to correctly associate the localization job and package.
  1. Navigate to the localization job for which you want to upload localized content back to Heretto CCMS by doing one of the following:
    OptionDescription
    Recommended: Upload localized content for a released map:
    1. In the content library, click the map for which you want to upload localized content. The Resource Details Drawer appears on the right side of the screen.

    2. In the Resource Details Drawer, select Releases.

    3. In the Releases tab, go to the proper release and click Localize.

    Upload localized content for a branched map:
    1. In the content library, click the map for which you want to upload localized content. The Resource Details Drawer appears on the right side of the screen.
    2. In the Resource Details Drawer, select Branches. You will see the list of branches related to your map.

    3. In the Branching tab, switch to the branch that contains the map for which you want to upload localized content.

    4. The Branching tab closes and you are back in the content library. Click the map for which you want to upload localized content.

    5. In the Resource Details Drawer on the right of the screen, select the Jobs Tab.
    Upload localized content for a standard map:
    1. In the content library, click the map for which you want to upload localized content. The Resource Details Drawer appears on the right side of the screen.
    2. In the Resource Details Drawer, select the Jobs Tab.

    Upload localized content for any map

    In the content library, go to Localization Jobs in the left pane.

  2. From the Localization Jobs list, select a job you want to upload localized content for. The value in the Job Type column will show XLIFF Package for this localization job.
  3. Click Upload XLIFF Package and in the Upload window, upload the ZIP file with localized content.
    You can easily identify the correct localization job by using the localization job number that you can see in both the ZIP file name and on the Localization Jobs list.
    localization jobs list

    If the localization process was done correctly, you will see the confirmation message saying: XLIFF package uploaded successfully!

  4. Under Localization Jobs in Progress, you can click any locale to verify if all files associated with your map are loaded to Heretto CCMS.
    After you load your XLIFF ZIP file, all your DITA files should show as Current. If there are any media files associated with your map, at this point they will show as Unavailable because you haven't loaded the Media Package for the map yet.
    xliff available localizations
Now you can either load your media content or publish the localized content.