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. This means that 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 Package, 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 easyDITA, easyDITA will show errors since it no longer is able to link the source text with the target text content correctly.

Reference File
A published map, for example, localization-reference.pdf.
Remember: To add a reference file to the localization job, you must publish a map before creating the localization job. We recommend including a reference file in localization packages and instructing the localization provider on where to find it.
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. 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 easyDITA
  1. Upload the localized XLIFF package to easyDITA. See Upload the Localized XLIFF Package
  2. If applicable, upload the localized media package to easyDITA. See Upload the Localized Media 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. Create an XLIFF Package for a map by doing one of the following:
    OptionDescription
    Recommended: Create the XLIFF Package for a released map:
    1. In the content library, right-click the map and select Releases .

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

    Create the XLIFF Package for a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to localize.
    2. In the content library, right-click the map and select Localization Jobs .
    Create the XLIFF Package for a standard map:

    In the content library, right-click the map and select Localization Jobs .

  2. From the New Localization Job drop-down menu, select XLIFF Package , then click Go .
  3. In the localization manager, configure and save your localization job: 
    1. In the Project 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.

    2. In the Manager field, leave your email address or change it to a different person.

      In the Manager field, you can add any string of characters. However, we recommend that you use it to add an email address to an easyDITA user who is responsible for the localization job. As a result, your localization provider will have this information in the project-notes.txt file in the XLIFF Package.

    3. In the Pick Target Locales field, add one or more target languages.
    4. Optional: Under Pick Reference Content to Include, select the reference content you created earlier.

      Even though this step is optional, we recommend always adding reference content, for example a PDF or HTML output. It will be added to your XLIFF package in a separate folder.

    5. Click Save .
  4. Click Download Localization Package and save the ZIP package to your computer.
    A ZIP file named companypackage type-localization-job-number.zip, for example Jorsekxliffpackage-localization-job-101.zip, is saved to your computer. The ZIP file contains the following elements:
    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 

  5. Complete one of the following actions:
    • If no media files, for example, diagrams or screen captures, 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.

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.
    Figure 1. Zipped and unzipped XLIFF files
  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 easyDITA.

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 easyDITA and verify the localization.
Important: Do not rename the XLF file or the XLIFF ZIP files of localized content.  easyDITA 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 easyDITA to correctly associate the localization job and package.
  1. Upload localized content for a map by doing one of the following:
    OptionDescription
    Recommended: Upload localized content for a released map:
    1. In the content library, right-click the map and select Releases .

    2. In the Releases tab, go to the release for which you want to upload content and click Localize .

    Upload localized content for a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to upload.

    2. In the content library, right-click the map and click Localization Jobs .

    Upload localized content for a standard map: In the content library, right-click the map and click Localization Jobs .
  2. In the Localization Jobs in Progress tab, click the localization job for which you want to upload 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 the Localization Jobs in Progress tab.
  3. Click Upload Localized Content and, in the Upload window, upload the ZIP file with localized content.
  4. Go back to the localization manager and open the Available Localizations tab to verify if all files associated with your map are loaded to easyDITA.
    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.
Now you can either load your media content or publish the localized content. 

Upload the Localized Media Package

Upload your localized media ZIP file. When your localization provider is done localizing your content, they send you an identical media ZIP file with the same content you originally provided. The only difference is that the media files in the target language folder(s) are now localized. Load the ZIP file to easyDITA and verify that the localization is complete.
  1. Upload localized content for a map by doing one of the following:
    OptionDescription
    Recommended: Upload localized content for a released map:
    1. In the content library, right-click the map and select Releases .

    2. In the Releases tab, go to the release for which you want to upload content and click Localize .

    Upload localized content for a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to upload.

    2. In the content library, right-click the map and click Localization Jobs .

    Upload localized content for a standard map: In the content library, right-click the map and click Localization Jobs .
  2. In the Localization Jobs in Progress tab, select the localization job you want to upload localized content for.

    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 the Localization Jobs in Progress tab.

  3. Click Upload Localized Content and, in the Upload window, upload the ZIP file with localized content.
  4. In the localization manager, click show resources and verify if all files associated with your map are uploaded to easyDITA.

    After you upload your media ZIP file, all your media files should show as Current.

Your localized DITA content is now uploaded to easyDITA.