Tutorials
Table of Contents
Tutorials
Localizing Content

Localization Overview

easyDITA allows you to create several localization packages to choose from depending on what type and amount of content you need to localize. For example, you can use XLIFF Package to localize text only or Source Package to localize both text and media. You can localize standard, released, and branched content.
section

XLIFF Package Localization

XLIFF Package is a common localization format for Computer-assisted Translation (CAT) tools. easyDITA allows you to create XLIFF packages to localize your content. You create XLIFF packages from a map.
When you create an XLIFF Package, your map along with the associated DITA files are transformed to form one Extensible LADAR Format (XLF) file with the source text and placeholders for the target text for each target language.
Because XLF is one file with all content, XLIFF packages are useful especially for the localization of small publications and for projects that can be completed by one translator.
The XLF file contains all the text content from the dependencies of the map, including the resource-only topics. It does not contain any media content.
section

Source Package Localization

Source Package is a localization bundle that you can create from a map. Source Package bundles together all files related to your map, including DITA and media files, in the form of a ZIP file that you can download and send to your localization provider. This means that, unlike in the XLIFF Package, files in the Source Package are not transformed to a different file format, they are sent in their original form.
All files in the Source Package are stored in a folder structure that is identical to your folder structure. Source Package contains all your warehouse and variable content.
Because they contain multiple DITA and media files, Source packages are useful especially for the localization of large publications and for projects that require cooperation of two or more translators.
Source Package contains all your warehouse and variable content. It is stored in the Source Package in a folder structure that is identical to your easyDITA folder structure.
section

Media Package Localization

Media Package is a localization bundle that you can create from a map. Media Package bundles together all media files related to your map, for example, diagrams or screen captures, in the form of a ZIP file that you can download and send to your localization provider. No DITA maps or topics are included.
The media files are located in a folder structure that is identical to your easyDITA folder structure.
Media packages are useful especially when used together with the XLIFF Package, which contains no media content, and to send media files only for localization.
section

Release and Branch Localization

In easyDITA, you can localize not only standard maps but also released and branched maps. Standard maps are the maps that are accessible from the master branch. Released and branched maps are accessible from the Releases Tab and a specific branch, respectively. Releases and branches are versioning tools.
Releases enable you to archive content at a specific point in time. The released version can then be downloaded, branched, published, and localized whenever you want.
Branches enable you to create a parallel set of content so you can edit the branched content without affecting the original content and push changes from one branch to another.
section

Locales

Locales are versions of your content in a target language, for example, in Canadian French or Polish. In easyDITA, you can easily view the locales for a map, topic, or media file in the Locales Tab. The locales listed in the Locales Tab are locales for the standard map and the locales created for the releases and branches of the map. Standard maps are the maps that are accessible from the master branch. Released and branched maps are accessible from the Releases Tab and a specific branch, respectively.

Localization Manager Overview

In easyDITA, all your localization jobs for a map are available in the Localization Manager . You can create numerous localization jobs for one map. In each localization job, you can add one or more locales, that is, target languages.
section

Localization Manager

Localization Manager sorts localization jobs in two tabs: Localization Jobs in Progress Tab and Available Localizations Tab. Localization Manager also shows localization jobs that are marked complete.

Localization Jobs in Progress Tab
Lists all localization jobs, regardless of whether content in the target language is already uploaded to easyDITA or not.
Available Localizations Tab
Lists localization jobs for which at least part of the content in the target language is already uploaded to easyDITA.
Completed Localization Jobs Section
Lists all completed localization jobs for a map along with the project manager and time of completion. Once a localization job is marked complete, the process cannot be undone. The section is created automatically when the first localization job for a map is marked complete.
section

Localization Jobs In Progress Tab

In the Localization Manager , you can view an overview and details of each localization job.
The overview provides information about the localization job number, the locales selected for the job, the type of localization package, information about the manager, and creation date for the localization job. Here is an example overview of two localization jobs.

# (Number)
The number of the localization job. Helps you quickly identify the correct localization job, for example, when uploading localized package to easyDITA.
Locales
Target languages selected for the localization job. For one localization job, there must be at least one locale selected.
Type
Type of the localization package selected for the localization job. By default, you can create XLIFF Package, Source Package, Media Package, and XTM Package.
Manager
Information about the person responsible for the localization job. Usually it contains an email address.
Created Date
The date and time at which the localization job was created.
section

Localization Jobs

When you click a localization job, you see its details, including project notes and status of resources. From this view, you can also perform actions related to this localization jobs: download localization package, upload localized content, mark the job complete, and cancel the job.

Project Notes
Information about the project. Usually used to provide information for the localization provider.
Status of Resources
Provides information about the status of the localized version of a file. There are three types of statuses: Current, Out of Date, Unavailable.

Current, represented by green, indicates that the localization of a file is successfully loaded to easyDITA
Out of Date, represented by yellow, indicates that the localized version of the file is not current any more, because the source language file was modified while its localized version was not updated. In other words, the Out of Date status indicates the file requires localization.
Unavailable, represented by red, indicates that the localized version of the file was not loaded to easyDITA.
Download Localization Package
Downloads a ZIP package containing all files related to the localization job. The ZIP package is sent to a localization provider for localization.
Upload Localized Content
Enables you to upload a ZIP package you received from your localization provider after they have finished localizing your content.
Mark Job Complete
Moves your localization job to the Completed Localization Jobs section, where your localization job is kept as an uneditable record. This action cannot be undone.
Cancel Job
Deletes your localization job from the Localization Manager . You can cancel only the localization jobs that are not marked complete yet. No record of a canceled localization jobs is kept.  
section

Language Code Table

From easyDITA, you can localize your content to numerous locales, that is target languages. You select locales when you create a localization job. Here is a list of all locales available by default in easyDITA.

Language Code Language name
ar Arabic
ar-sa Arabic (Saudi Arabia)
ar-eg Arabic (Egypt)
be Belarusian
be-by Belarusian (Belarus)
bg Bulgarian
bg-bg Bulgarian (Bulgaria)
ca Catalan
ca-es Catalan (Spain)
cs Czech
cs-cz Czech (Czech Republic)
da Danish
da-dk Danish (Denmark)
de German
de-ch German (Switzerland)
de-de German (Germany)
el Greek
el-gr Greek (Greece)
en English
en-au English (Australia)
en-ca English (Canada)
en-gb English (United Kingdom)
en-us English (United States)
es Spanish
es-es Spanish (Spain)
es-co Spanish (Colombia)
es-419 Latin America and Caribbean
et Estonian
et-ee Estonian (Estonia)
fi Finnish
fi-fi Finnish (Finland)
fr French
fr-be French (Belgium)
fr-ca French (Canada)
fr-ch French (Switzerland)
fr-fr French (France)
he Hebrew
he-il Hebrew (Israel)
hr Croatian
hr-hr Croatian (Croatia)
hu Hungarian
hu-hu Hungarian (Hungary)
hi Hindi
hi-in Hindi (India)
is Icelandic
is-is Icelandic (Iceland)
it Italian
it-ch Italian (Switzerland)
it-it Italian (Italy)
ja Japanese
ja-jp Japanese (Japan)
ko Korean
ko-kr Korean (Korea)
lt Lithuanian
lt-lt Lithuanian (Lithuania)
lv Latvian
lv-lv Latvian (Latvia)
mk FYRO Macedonian
mk-mk FYRO Macedonian (Former Yugoslav Republic of Macedonia)
nl Dutch
nl-be Dutch (Belgium)
nl-nl Dutch (Netherlands)
no Norwegian
no-no Norwegian
nn-no Norwegian (Nynorsk) (Norway)
nb-no Norwegian (Bokmål) (Norway)
pl Polish
pl-pl Polish (Poland)
pt Portuguese
pt-br Portuguese (Brazil)
pt-pt Portuguese (Portugal)
ro Romanian
ro-ro Romanian (Romania)
ru Russian
ru-ru Russian (Russia)
sk Slovak
sk-sk Slovak (Slovakia)
sl Slovenian
sl-si Slovenian (Slovenia)
sr Serbian
sr-rs Serbian (Cyrillic script)
sr-sp Serbian (Cyrillic script)
sr-latn-rs Serbian (Latin script)
sv Swedish
sv-se Swedish (Sweden)
th Thai
th-th Thai (Thailand)
tr Turkish
tr-tr Turkish (Turkey)
uk Ukrainian
uk-ua Ukrainian (Ukraine)
ur Urdu
ur-pk Urdu (Islamic Republic of Pakistan)
zh Chinese
zh-cn Chinese (Simplified, PRC)
zh-hans Chinese (Simplified)
zh-tw Chinese (Traditional, Taiwan)
zh-hant Chinese (Traditional)

XLIFF Localization Overview

XML Localization Interchange File Format (XLIFF) is an XML-based format created to standardize the file exchange in the localization process. XLIFF packages are a common format for Computer-assisted Translation (CAT) tools. easyDITA allows you to create XLIFF packages to localize your content. You create XLIFF packages from a map.

section

XLIFF Package

When you create an XLIFF Package, your map along with the associated DITA files are transformed to form one Extensible LADAR Format (XLF) file with the source text and placeholders for the target text for each target language. For example:

< trans-unit id="p-7">  	< source> When you go into the garage, be prepared to get your hands dirty!< /source>  	< target> When you go into the garage, be prepared to get your hands dirty!< /target>  < /trans-unit> 

The localization provider modifies only content in the target element. If they modify content in the source element, it would cause errors in easyDITA since it would no longer be able to link the source text with the target text.

Because XLF is one file with all content, XLIFF packages are useful especially for the localization of small publications and for projects that can be completed by one translator.
Apart from the XLF file, the package also contains project notes (TXT file) and, optionally, a folder with a reference file (for example, a PDF).

As you can see, when you create an XLIFF Package, the associated media files are not bundled in it. To send media files for localization, create a Media Package.
section

Warehouse Content and Variables

The XLF file contains all the text content from the dependencies of the map, including the resource-only topics. As a result, you can be sure that your content referenced by using content references (conref) or content key references (conkeyref) will be localized. Let’s take a look at an example.
Here, you can see the Classic Toaster product name located in the warehouse topic:

In the XLF file, the product name is in a source element, followed by the same content in a target element. Later, the localization provider changes the content of the target element for their locale. For example, here are source and target elements before localization: 

 < trans-unit id="ph-9">  	< source> Classic Toaster< /source>  	< target> Classic Toaster< /target>   < /trans-unit> 

And here are the same elements after localization:

 < trans-unit id="ph-9">  	< source> Classic Toaster< /source>  	< target> Toster Klasyczny< /target>   < /trans-unit> 
section

Translate=no

Only translatable elements are included in the XLF file of the XLIFF Package. This means that elements with the translate attribute set to no are not included in the XLF file.
section

Localization of Releases

In easyDITA, you can localize releases. Releases are a versioning tool that enables you to archive content at a specific point in time. The released version can then be downloaded, branched, published, and localized whenever you want.  
When you create a release, an archive of the content at its current state is created. The content that is archived in the release version cannot be modified. It is a permanent and unalterable archive. You can, however, continue to edit the original document normally.
For the released content, you can create all types of localization packages.
section

Localization of Branched Content

In easyDITA, you can localize branched content. Branches are a versioning tool that enable you to create a parallel set of content so you can edit the branched content without affecting the original content and push changes from one branch to another.
When a map is branched, full copies of each component are created in the new branch, along with its link dependencies. This allows you to edit the branched map without affecting the ‘original’ map. Then when you’re ready, you can merge or replace changes from one branch into another.
For the branched content, you can create all types of localization packages.

XLIFF Localization Considerations

Make sure that your localization provider understand the structure of the XLIFF Package and the basic rules of working with it.

Here is an example XLIFF Package:

section

XLF File

In the XLIFF Package, the most important file for the localization provider is the XLF file, for example, pl-_-.xlf or fr-ca-_-.xlf. This is the 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.
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 link content correctly.

section

Reference File

The XLIFF Package also contains a folder with a reference file, for example, localization-reference-pdf. The reference file is an output of the map, for example, a PDF or HTML. To add this reference file to the localization job, you must create the file before creating the localization job. The name of the folder is the name of the publish you created. We recommend to always add the reference file to your XLIFF package and instruct the localization provider where to find it.
section

Project Notes

The XLIFF Package contains notes that you add in the Project Notes field when creating a localization job. Project notes are a handy solution to share information with the localization provider.
If you add project-critical information in the Project Notes field when creating a localization job, remember to inform the localization provider to read the project-notes.txt file included in the XLIFF Package. Otherwise, they may ignore this important TXT file.
section

Localization Job Manager

For each localization job, you can specify a manager. By default, this role is assigned to you, but you can change it. Manager is the user responsible for the localization job. The user assigned to the manager role does not, however, have any special permissions or rights to the localization job – all easyDITA users can access it and work with it. The email address of the manager is included in the project-notes.txt file in the XLIFF Package.
section

Media Content

XLIFF Packages do not contain media files, such as screen captures and diagrams. If your publication contains media files, you also need to create a Media Package and send it for localization.
Unlike Source Package, XLIFF Package does not contain media files, for example, diagrams and screen captures. This is why, if your map contains media files that require localization, you need to create and send a Media Package along with the XLIFF Package to the localization provider.
section

Localized XLIFF Package

When the localization provider is ready with the localization of your content they need to send the localized, zipped package back to you so that you can load it to easyDITA. The ZIP you receive from the localization provider must contain all files and folders they received. Last but not least, to avoid errors, they need to zip the files correctly.

Creating Reference Content for Your XLIFF Package

When you create an XLIFF Package, you can include reference content for the localization provider. This reference content is an output of your map, for example, PDF or HTML.

We recommend always adding reference content to your XLIFF Package. You create the reference content before creating a localization job by publishing your map to a specific output.

  1. Create reference content for your localization provider by doing one of the following:

    Create reference content for a standard map:
    1. In the Content Manager , right-click the map and select Preview .

    2. In the Preview Tab, click Publish .

    Create reference content for a released map:
    1. In the Content Manager , right-click the map and select Releases .

    2. In the Releases Tab, go to the release you want to localize and click Output .

    Create reference content 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 Manager , right-click the map and select Preview .
    3. In the Preview Tab, click Publish .
  2. In the Publishing interface, select DITA Open Toolkit.
  3. In the Publication Manager, click New Publish .
  4. From the Available Publishing Scenarios list, select the output type, for example, PDF. 
  5. In the Basic Info section, configure the publish and publish the content:

    Step Information
    Note that parameters are specific to each publishing scenario as defined by your system administrator. Typical parameters are Transformation Type (transtype, which defines the output format), locale, or DITAVAL file which lets you select a configuration file in the DITAVAL format.

    1. In the Description field, enter a description that will be meaningful for your localization provider, for example Localization Reference (PDF).

      Step Information
      The description of your publish is used as the name of the folder that contains your reference content in the XLIFF Package. This is why it’s important for the description to be meaningful.

    2. In the Choose Locale field, select your source language, for example, Source (en).
    3. Configure any other parameters of the publishing scenario.
    4. Click Publish .
result

You have reference content for your localization job. You are now ready to create the localization job.

Creating an XLIFF Package

When you create an XLIFF package for a map one of the files created is an XLF file with all your content for that map. This means that out of multiple DITA files, one XLF life is created.

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.

prereq
Before you create the XLIFF Package, we recommend that you create reference content for your map. See Creating Reference Content for Your XLIFF Package.
  1. Create an XLIFF Package for a map by doing one of the following:

    Create the XLIFF Package for a standard map:
    In the Content Manager , right-click the map and select Localization Jobs .
    Create the XLIFF Package for a released map:
    1. In the Content Manager , 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 Manager , right-click the map and select Localization Jobs .
  2. From the New Localization Job drop-down menu, select XLIFF Package . Click Go .
  3. In the Localization Manager , configure and save your localization job: 

    Step Information
    1. In the Project Notes field, enter information about the project, including information for the localization provider. 

      Step Information
      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.

      Step Information
      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 at hand since it is added to 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.

      Step Information
      Even though this step is optional, we recommend to always add reference content, for example PDF or HTML. It will be added in a folder to your XLIFF package.
    5. Click Save .
    Expected Result
    Your localization job displays. You can view the project notes, manager, locales, resources, and status of resources.
  4. Click Download Localization Package and save the ZIP package to your computer. 

    Expected Result
    A ZIP file named company package 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 element
    • 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 your localization provider is not well familiar with localizing easyDITA XLIFF Packages, share with them Localizing XLIFF Content.
    • If media files associated with your map require localization, complete Creating a Media Package.
result
Your XLIFF Package is ready for localization.

Creating a Media Package

When you create an XLIFF Package, no media files associated with your map are included in it. This is why if your map contains media files, for example, diagrams or screen captures, that require localization, you need to create a Media Package and send it to the localization provider along with your XLIFF Package. Media Packages are created from the map.
prereq
Before you create a Media Package, verify that the media file names contain no illegal characters, for example, spaces. If they do, you will not be able to upload the localized package back to easyDITA.

  1. Create an Media Package for a map by doing one of the following: 

    Create the Media Package for a standard map: In the Content Manager , right-click the map for which you want to create the Media Package and click Localization Jobs .
    Create the Media Package for a released map:
    1. In the Content Manager , 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 Media 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 Manager , right-click the map and click Localization Jobs .

  2. From the New Localization Job drop-down menu, select Media Package . 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. 
    2. In the Manager field, leave your email address or change it to a different person.

      Step Information
      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 at hand.

    3. In the Include field, select All Media if you localize the files for the first time or Only Changed Resources if you have already localized the files.
    4. In the Pick Target Locales field, add a target language or more. 
    5. Click Save .
    Expected Result
    Your localization job displays. You can view the project notes, manager, locales, resources, and status of resources.

  4. Click New Localization Job and save the ZIP file to your computer. 

    Expected Result
    A ZIP file named media-localization-package-number.zip, for example media-localization-package-108.zip, is saved to your computer. The ZIP file contains all media files associated with your map. The files are located in a folder structure that is identical to your easyDITA folder structure. 

  5. Send your Media ZIP file to your localization provider.

    Step Information
    If your localization provider is not well familiar with localizing easyDITA Media Packages, share with them Localizing Media Content.

result
The localization process of your media content is now started.

Localizing XLIFF Content

Localization is usually performed by an external localization provider. Sometimes, however, translators are available internally within the team. Regardless of whether you are a translator or you send your content for localization, you should know how to work with the XLIFF Package when localizing content so that the package can be loaded back to easyDITA successfully.
  1. Save the ZIP file you received for localization to your computer and unzip it.

    Step Information
    Important:Do not change the name of the folder to which you unzip the file. Any modifications will cause errors when loading the package back to easyDITA.

    Zipped and correctly unzipped XLIFF files:

  2. Open the unzipped XLIFF folder and familiarize yourself with its contents:

    Step Information
    1. Go to the reference content folder, for example localization-reference-pdf, and open the reference content it contains, for example, PDF or HTML, created from the map you are about to localize.
    2. Read the project-notes.txt file that contains an email to 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.

    Step Information
    Important:Do not modify any content outside of the target elements. If you modify content in the source elements, when loading the ZIP file back to easyDITA, it will show errors and the load will not be completed.
    The XLF file contains all text content that requires localization. This excludes media files. If media files require localization, you should send them in a separate Media Package.
  4. When you finish localizing content, save the XLF file to the original unzipped folder under original file names and extensions.
  5. Zip the localized XLIFF Package by right-clicking it and compressing it to a ZIP file. Name the new ZIP file exactly the same as the original ZIP file.

    Step Information
  6. Send the localized ZIP file back to the project manager or upload it to easyDITA.
result
The XLIFF package contains localization and is compressed correctly.

Localizing Media Content

When you localize a map by using an XLIFF Package, you need to send your media content associated with this map for localization in a separate package. This is when you use the Media Package. Learn how to work with the Media Package to ensure the package with localized content can be loaded back to easyDITA successfully.
  1. Save the ZIP file you received for localization to your computer and unzip it.

    Step Information
    Important: Do not change the name of the folder to which you unzip the file. Any modifications will cause errors when uploading the package back to easyDITA.

    Zipped and correctly unzipped media files:

  2. Open the unzipped Source Package folder and familiarize yourself with its contents:

    1. Navigate to a target language folder, for example fr-ca or pl, and open the manifest.xml file it contains.

      Step Information
      The manifest.xml file contains a list of media resources and their destinations in the package. Use it to effectively navigate the folder structure of the Media Package and ensure all files are localized.

  3. Navigate down the target language folder to media files and localize them.

    Step Information
    Important:Do not modify the file names, their extensions, or location. If you modify any of these, when uploading the ZIP file back to easyDITA, it will show errors and the upload will not be completed.

  4. When you finish localizing the media files, save them back to their original location under original file names and extensions.
  5. Zip the localized Media Package by right-clicking it and compressing it to a ZIP file. Name the new ZIP file exactly the same as the original ZIP file.

    Step Information

  6. Send the localized ZIP file back to the project manager or upload it to easyDITA.
result
The Media Package contains localization and is correctly compressed.

Uploading the Localized XLIFF ZIP File

When your localization provider is ready localizing 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 if localization is complete.
  1. Upload localized content for a map by doing one of the following:

    Upload localized content for a standard map: In the Content Manager , right-click the map and click Localization Jobs .
    Upload localized content for a released map:
    1. In the Content Manager , 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 Manager , 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. 

    Step Information
    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.

    Step Information
    After you load your XLIFF ZIP file, all your DITA files should display as Current. If there are any media files associated with your map, at this point they will display as Unavailable because you haven’t loaded the Media Package for the map yet.

result

Your localized DITA content is now loaded to easyDITA. Now, you can either load your media content or publish the localized content. 

Uploading the 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 are now localized. Load the ZIP file to easyDITA and verify that the localization is complete.
context
  1. Upload localized content for a map by doing one of the following:

    Upload localized content for a standard map: In the Content Manager , right-click the map and click Localization Jobs .
    Upload localized content for a released map:
    1. In the Content Manager , 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 Manager , 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.

    Step Information
    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.

    Step Information
    After you upload your media ZIP file, all your media files should display as Current.

result
Your localized DITA content is now uploaded to easyDITA.

Publishing Localized XLIFF Content

After you receive localized content and upload it to easyDITA, it is a good practice to publish the content, for example to HTML or PDF, and verify that all content is localized and appears correctly in the context.  

It is especially important to verify elements that are content referenced (conref) or content key referenced (conkeyref). Make sure to verify if media files are localized correctly too.

  1. Publish a localized map by doing one of the following:

    Publish the localized version of a standard map:
    1. In the Content Manager , right-click the map and select Preview .

    2. In the Preview Tab, click Publish .

    Publish the localized version of a released map:
    1. In the Content Manager , right-click the map and select Releases .

    2. In the Releases Tab, go to the release you want to publish and click Output .

    Publish the localized version of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to publish.
    2. In the Content Manager , right-click the map and select Previous .
    3. In the Preview Tab, click Publish .
  2. In the Publishing interface, select DITA Open Toolkit.
  3. In the Publication Manager, click New Publish .
  4. From the Available Publishing Scenarios list, select the output type, for example, PDF.
  5. In the Basic Info section, configure parameters for each publishing scenario you have selected:

    Step Information
    Note that parameters are specific to each publishing scenario as defined by your system administrator. Typical parameters are Transformation Type (transtype, which defines the output format), locale, or DITAVAL file which lets you select a configuration file in the DITAVAL format.
    1. In the Description field, enter a meaningful description of your publish that will include information about which localization you publish.
    2. In the Choose Locale field, select the locale, so target language, you want to publish.
    3. Configure any other parameters of each publishing scenarios.
    4. Click Publish .
result
A localized version of your map is published. You can now download the published content and view it. If the localized content is correct, you can mark your localization job complete.

Note: Marking your job complete moves your localization job to the Completed Localization Jobs section, where your localization job is kept as an uneditable record. This action cannot be undone.

Viewing Localized Content

Locales are versions of your content in a target language, for example, in Canadian French or Polish. In easyDITA, you can easily view the locales for a map, topic, or media file in the Locales Tab. The locales listed are locales for the standard map and the locales created for the releases and branches of the map.
  1. In the Content Manager , navigate to the map, topic, or media file for which you want to view locales.
  2. Right-click the file and select Locales .
  3. In the Locales Tab, click the locale you want to view.

    Expected Result
    The preview of the locale displays.

result

Resending Content for Localization

After your localization provider returns your localized content, it may turn out it needs correction. In such a situation, you can resend it to the localization provider.
Note:If the localization job for your map is marked complete, create a new localization job and send it to the localization provider. See Creating an XLIFF Package or Creating a Media Package.
  1. Resend a map to the localization provider by doing one of the following:

    Resend a standard map: In the Content Manager , right-click the map and select Localization Jobs .
    Resend a released map:
    1. In the Content Manager , right-click the map and select Releases .

    2. In the Releases Tab, go to the release you want to localize and click Locales .

    Resend a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to resend.
    2. In the Content Manager , right-click the map and select Localization Jobs .
  2. In the Localization Jobs in Progress Tab, click the localization job that you want to resend to the localization provider.

    Step Information
    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 Download Localization Package , save the ZIP file to your computer and send it to the localization provider with instructions of what needs correction. 

    Step Information
    Remember:If both your DITA and media content need to be resent to the localization provider, you need to send them two packages: XLIFF Package and Media Package.

result

Your content is sent for corrections to the localization provider. When you receive the corrected content, load it to easyDITA.

Modifying Localized Topic Content

After your localization provider returns your localized content, it may turn out it needs correction. In such a situation, you can modify locales yourself directly in easyDITA.

Locales are versions of your content in a target language, for example, in Canadian, French, or Polish. In easyDITA, you can easily view the locales for a map, topic, or media file in the Locales Tab. The locales listed are locales for the standard map and the locales created for the releases and branches of the map.

  1. Modify localized file of a standard map:
    1. In the Content Manager , right-click the localized topic you want to modify and select Locales .
    2. In the Locales Tab, select the locale, that is a target language, that you want to modify.
    3. Click the topic element you want to modify and, in the Edit Content window, edit the locale for the topic. Click Save
    Modify localized file of a released map:
    1. In the Content Manager , right-click the localized topic you want to modify and select Releases .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, that you want to modify.

    4. From the list of localized files, click the one you want to modify.

    5. Click the topic element you want to modify and, in the Edit Content window, edit the locale for the topic. Click Save
    Modify localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized topic that you updated and select Locales .

    3. In the Locales Tab, select the locale, that is a target language, that you want to modify.
    4. Click the topic element you want to modify and, in the Edit Content window, edit the locale for the topic. Click Save
    Step Information

result
Your changes are saved to the Translation Memory (TM). They will appear in the new publish of the localized content.

Downloading and Uploading Individual Localized Files

Sometimes, you may need to modify individual localized DITA or media files outside of easyDITA. You can do it from the Locales Tab.

Locales are versions of your content in a target language, for example, in Canadian French or Polish. The locales listed in the Locales Tab are locales for the standard map and the locales created for the releases and branches of the map.

  1. Download a localized DITA or media file to your computer:

    Download a localized file of a standard map:
    1. In the Content Manager , right-click the localized file you want to modify and select Locales .

    2. Select the locale, that is a target language, that you want to modify and click Download Locale . Save the file to your computer.

    Download a localized file of a released map:
    1. In the Content Manager , right-click the localized file you want to modify and select Locales .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, that you want to modify.

    4. From the list of localized files, click the one you want to modify.

    5. In the locale preview window, click Download Locale . Save the file to your computer.

    Download a localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized file you want to modify and select Locales .

    3. Select the locale, that is a target language, that you want to modify and click Download Locale . Save the file to your computer.

  2. Modify and save the file on your computer.

    Step Information
    Do not change the file name or extension. Otherwise, you will not be able to upload the file back to easyDITA

  3. Upload the updated file:

    Upload the localized file of a standard map:
    1. In the Content Manager , right-click the localized file you updated and select Locales .

    2. In the Locales Tab, click Upload Locale .

    3. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    4. In the Upload window, click Browse and navigate to the updated file. Click Open .

    Upload the localized file of a released map:
    1. In the Content Manager , right-click the localized file you updated and select Releases .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, you updated.

    4. From the list of localized files, click the file you updated.

    5. In the locale preview window, click Upload Locale .

    6. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    7. In the Upload window, click Browse and navigate to the updated file. Click Open .

    Upload the localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized topic that you updated and select Locales .

    3. In the Locales Tab, click Upload Locale .

    4. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    5. In the Upload window, click Browse and navigate to the updated file. Click Open .

result
The file with updated locale is now uploaded to easyDITA. Updates are displayed in the Locales Tab.

Source Package Localization Overview

section

Source Package

When you create a Source Package, all of the DITA and media files associated with your map are bundled into one ZIP file. This means that the localization provider receives one or more maps, a number of DITA topics, and related media files in the ZIP file. The package contents are organized in a folder structure that is identical to your easyDITA folder structure.
The Source Package contains a folder named source-language-reference that contains source reference files, as well as one folder for each localization. This folder is named after the target locale, for example, the folder for Canadian French localization is named fr-ca, and the folder for Polish localization is named pl
Here is an example Source Package: 

section

Warehouse Content and Variables

Source Package contains all your warehouse and variable content. It is stored in the Source Package in a folder structure that is identical to your easyDITA folder structure. As a result, you can be sure that content your source includes through content references (conref) or content key references (conkeyref) will be localized.
section

Translate=no

Files and file elements with the translate attribute set to no are included in the Source Package. The translate=no information is saved in the Source Package so that the localization provider can use it during the localization process.
section

Localization of Releases

In easyDITA, you can localize releases. Releases are a versioning tool that enables you to archive content at a specific point in time. The released version can then be downloaded, branched, published, and localized whenever you want.  
When you create a release, an archive of the content at its current state is created. The content that is archived in the release version cannot be modified. It is a permanent and unalterable archive. You can, however, continue to edit the original document normally.
For the released content, you can create all types of localization packages.
section

Localization of Branched Content

In easyDITA, you can localize branched content. Branches are a versioning tool that enable you to create a parallel set of content so you can edit the branched content without affecting the original content and push changes from one branch to another.
When a map is branched, full copies of each component are created in the new branch, along with its link dependencies. This allows you to edit the branched map without affecting the ‘original’ map. Then when you’re ready, you can merge or replace changes from one branch into another.
For the branched content, you can create all types of localization packages.

Source Package Localization Considerations

Make sure that your localization provider understands the structure of the Source Package and the basic rules of working with it.

Here is an example Source Package:

section

Target Language Folder

Target language folder, for example, fr-ca or pl, is the folder your localization provider uses to localize content. When you create a Source Package you select locales, that is, target languages, for your localization job. For each of the locales, a separate folder is created in the Source Package. The folders are named after the names of locales. For example, the folder for Canadian French localization is named fr-ca, and the folder for Polish localization is named pl. Each target language folder contains one or more maps together with all their associated DITA and media files. The files are located in a folder structure that is identical to your easyDITA folder structure.
section

Source Language Reference Folder

Each Source Package contains a folder named source-language-reference that contains one or more maps together with all their associated DITA and media files in the source language. The files are located in a folder structure that is identical to your easyDITA folder structure. The files can be used by your localization provider as a reference during the localization process. None of the files located in this folder should be localized. To localize content, your localization provider should use the target language folder(s). 
section

Localization Job Manager

For each localization job, you can specify a manager. By default, this role is assigned to you, but you can change it. Manager is the user responsible for the localization job. The user assigned to the manager role does not, however, have any special permissions or rights to the localization job – all easyDITA users can access it and work with it.
section

Media Content

Source Package contains all media content related to the map for which you create the Source Package. Media files are located in a folder structure that is identical to your easyDITA folder structure. As a result, when you send a Source Package to your localization provider, you can be sure that it contains all content that requires localization.
section

Localized Source Package

When the localization provider is ready with the localization of your content they need to send the localized, zipped package back to you so that you can load it to easyDITA. The ZIP you receive from the localization provider must contain all files and folders they received. Last but not least, to avoid errors, they need to zip the files correctly.

Creating a Source Package

When you create a Source Package for a map, the content associated with the map is bundled together and made available to you in the form of a ZIP file that you can download and send to your localization provider.

The Source Package contains all DITA files, including your warehouse topics and media files. The files are located in a folder structure that is identical to your easyDITA folder structure.

  1. Create a Source Package for a map by doing one of the following:  

    Create the Source Package for a standard map: In the Content Manager , right-click the map and select Localization Jobs .
    Create the Source Package for a released map:
    1. In the Content Manager , 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 Source 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 Manager , right-click the map and select Localization Jobs .
  2. From the New Localization Job drop-down menu, select Source Package . Click Go .
  3. In the Localization Manager , configure and save your localization job:

    Step Information

    1. In the Project Notes field, enter information about the project, including information for the localization provider. 

      Step Information

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

      Step Information
      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 at hand.

    3. In the Include field, select All Media if you localize the files for the first time or Only Changed Resources if you have already localized the files.
    4. In the Pick Target Locales field, add one or more target languages.
    5. Click Save .
    Expected Result
    Your localization job displays. You can view the project notes, manager, locales, resources, and status of resources.

  4. Click Download Localization Package and save the ZIP file to your computer. 

    Expected Result
    A ZIP file named localization-job-number.zip, for example localization-job-106.zip, is saved to your computer. The ZIP file contains the following elements:

    where:

    • fr-ca folder contains DITA and media files that will be localized, in this case, into Canadian French (fr-ca)
    • pl folder contains DITA and media files that will be localized, in this case, into Polish (pl)

    • source-language-reference folder contains DITA and media files that will be used by the localization provider as a reference for the localization process; no files in this folder should be modified

    In both folders, DITA and media files are located in a folder structure that is identical to your easyDITA folder structure.

  5. Send the ZIP file to your localization provider.

    Step Information
    If your localization provider is not well familiar with localizing easyDITA Source Packages, share with them Localizing Source Package Content.

result
Your Source Package is ready for localization.

Localizing Source Package Content

Localization is usually performed by an external localization provider. Sometimes, however, translators are available internally within the team. Regardless of whether you are a translator or you send your content for localization, you should know how to work with the Source Package when localizing content so that the package can be uploaded back to easyDITA successfully.
  1. Save the ZIP file you received for localization to your computer and unzip it.

    Step Information
    Important: Do not change the name of the folder to which you unzip the file. Any modifications will cause errors when uploading the package back to easyDITA.

    Zipped and correctly unzipped Source Package files:

  2. Open the unzipped Source Package folder and familiarize yourself with its contents:

    Step Information
    1. Go to the source-language-reference folder, and view the DITA and media files it contains for the localization provider’s reference.

      Step Information
      Important:Do not modify any content inside the source-language-reference folder. If you modify content in the source-language-reference folder, when uploading the ZIP file back to easyDITA it wll show errors and the upload will not be completed.
  3. In the target language folder, for example fr-ca or pl, navigate down the folder structure to the DITA and media files and localize them.

    Step Information
    Save localized files to their original location using their original file names and extensions.
  4. When you finish localizing all DITA and media files, zip the localized Source Package by right-clicking it and compressing it to a ZIP file. Name the new ZIP file exactly the same as the original ZIP file.

    Step Information
  5. Send the localized ZIP file back to the project manager or upload it to easyDITA.
result
The Source Package contains localization and is correctly compressed.

Uploading the Localized Source Package ZIP File

When your localization provider is done localizing your content, they send you an identical Source Package ZIP file with the same content. The only difference is that the DITA and media files are now localized. Upload the ZIP file to easyDITA and verify if localization is complete.
  1. Upload localized content for a map by doing one of the following:

    Upload localized content for a standard map: In the Content Manager , right-click the map and click Localization Jobs .
    Upload localized content for a released map:
    1. In the Content Manager , 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 Manager , 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.

    Step Information
    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 Upload Response window, verify that the files you upload match the correct files in easyDITA. Click Save

    Step Information
  5. In the Status of Resources view, verify that all resources in your localization job display as Current.

    Step Information
    The number in green should say 100%. This means all resources are current. 
result
Your localized DITA content is uploaded to easyDITA. You can now publish the localized content.

Publishing Localized Content

After you receive localized content and load it to easyDITA, it is a good practice to publish the content, for example, to HTML or PDF, and verify if all content is localized and appears correctly in the context.

It is especially important to verify elements that are content referenced (conref) or content key referenced (conkeyref). Make sure to verify if media files are localized correctly too.

  1. Publish a localized map by doing one of the following:

    Publish the localized version of a standard map:
    1. In the Content Manager , right-click the map and select Preview .

    2. In the Preview Tab, click Publish .

    Publish the localized version of a released map:
    1. In the Content Manager , right-click the map and select Releases .

    2. In the Releases Tab, go to the release you want to publish and click Output .

    Publish the localized version of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to publish.
    2. In the Content Manager , right-click the map and select Previous .
    3. In the Preview Tab, click Publish .
  2. In the Preview Tab, click Publish .
  3. In the Publishing interface, select DITA Open Toolkit.
  4. In the Publication Manager, click New Publish .
  5. From the Available Publishing Scenarios list, select the output type, for example, PDF.
  6. In the Basic Info section, configure parameters for each publishing scenario you have selected:

    Step Information
    Note that parameters are specific to each publishing scenario as defined by your system administrator. Typical parameters are Transformation Type (transtype, which defines the output format), locale, or DITAVAL file which lets you select a configuration file in the DITAVAL format.
    1. In the Description field, enter a meaningful description of your publish that will include information about which localization you publish.
    2. In the Choose Locale field, select the locale, so target language, you want to publish.
    3. Configure any other parameters of each publishing scenarios.
    4. Click Publish .
result
A localized version of your map is published. You can now download the published content and view it. If the localized content is correct, you can mark your localization job complete.

Note: Marking your job complete moves your localization job to the Completed Localization Jobs section, where your localization job is kept as an uneditable record. This action cannot be undone.

Viewing Localized Content

Locales are versions of your content in a target language, for example, in Canadian French or Polish. In easyDITA, you can easily view the locales for a map, topic, or media file in the Locales Tab. The locales listed are locales for the standard map and the locales created for the releases and branches of the map.
  1. In the Content Manager , navigate to the map, topic, or media file for which you want to view locales.
  2. Right-click the file and select Locales .
  3. In the Locales Tab, click the locale you want to view.

    Expected Result
    The preview of the locale displays.

result

Resending Content for Localization

After your localization provider returns your localized content, it may turn out it needs correction. In such a situation, you can resend it to the localization provider.
Note:If the localization job for your map is marked complete, create a new localization job and send it to the localization provider. See Creating a Source Package.
  1. Resend a map to the localization provider by doing one of the following:

    Resend a standard map: In the Content Manager , right-click the map and select Localization Jobs .
    Resend a released map:
    1. In the Content Manager , right-click the map and select Releases .

    2. In the Releases Tab, go to the release you want to localize and click Locales .

    Resend a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to resend.
    2. In the Content Manager , right-click the map and select Localization Jobs .
  2. In the Localization Jobs in Progress Tab, click the localization job that you want to resend to the localization provider.

    Step Information
    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 Download Localization Package, save the ZIP file to your computer and send it to the localization provider with instructions of what needs correction. 
result

Your content is sent for corrections to the localization provider. When you receive the corrected content, load it to easyDITA.

Modifying Localized Topic Content

After your localization provider returns your localized content, it may turn out it needs correction. In such a situation, you can modify locales yourself directly in easyDITA.

Locales are versions of your content in a target language, for example, in Canadian, French, or Polish. In easyDITA, you can easily view the locales for a map, topic, or media file in the Locales Tab. The locales listed are locales for the standard map and the locales created for the releases and branches of the map.

  1. Modify localized file of a standard map:
    1. In the Content Manager , right-click the localized topic you want to modify and select Locales .
    2. In the Locales Tab, select the locale, that is a target language, that you want to modify.
    3. Click the topic element you want to modify and, in the Edit Content window, edit the locale for the topic. Click Save
    Modify localized file of a released map:
    1. In the Content Manager , right-click the localized topic you want to modify and select Releases .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, that you want to modify.

    4. From the list of localized files, click the one you want to modify.

    5. Click the topic element you want to modify and, in the Edit Content window, edit the locale for the topic. Click Save
    Modify localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized topic that you updated and select Locales .

    3. In the Locales Tab, select the locale, that is a target language, that you want to modify.
    4. Click the topic element you want to modify and, in the Edit Content window, edit the locale for the topic. Click Save
    Step Information

result
Your changes are saved to the Translation Memory (TM). They will appear in the new publish of the localized content.

Downloading and Uploading Individual Localized Files

Sometimes, you may need to modify individual localized DITA or media files outside of easyDITA. You can do it from the Locales Tab.

Locales are versions of your content in a target language, for example, in Canadian French or Polish. The locales listed in the Locales Tab are locales for the standard map and the locales created for the releases and branches of the map.

  1. Download a localized DITA or media file to your computer:

    Download a localized file of a standard map:
    1. In the Content Manager , right-click the localized file you want to modify and select Locales .

    2. Select the locale, that is a target language, that you want to modify and click Download Locale . Save the file to your computer.

    Download a localized file of a released map:
    1. In the Content Manager , right-click the localized file you want to modify and select Locales .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, that you want to modify.

    4. From the list of localized files, click the one you want to modify.

    5. In the locale preview window, click Download Locale . Save the file to your computer.

    Download a localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized file you want to modify and select Locales .

    3. Select the locale, that is a target language, that you want to modify and click Download Locale . Save the file to your computer.

  2. Modify and save the file on your computer.

    Step Information
    Do not change the file name or extension. Otherwise, you will not be able to upload the file back to easyDITA

  3. Upload the updated file:

    Upload the localized file of a standard map:
    1. In the Content Manager , right-click the localized file you updated and select Locales .

    2. In the Locales Tab, click Upload Locale .

    3. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    4. In the Upload window, click Browse and navigate to the updated file. Click Open .

    Upload the localized file of a released map:
    1. In the Content Manager , right-click the localized file you updated and select Releases .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, you updated.

    4. From the list of localized files, click the file you updated.

    5. In the locale preview window, click Upload Locale .

    6. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    7. In the Upload window, click Browse and navigate to the updated file. Click Open .

    Upload the localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized topic that you updated and select Locales .

    3. In the Locales Tab, click Upload Locale .

    4. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    5. In the Upload window, click Browse and navigate to the updated file. Click Open .

result
The file with updated locale is now uploaded to easyDITA. Updates are displayed in the Locales Tab.

Media Package Localization Overview

Media Package is a localization bundle that you can create from a map. Media Package bundles together all media files related to your map, for example, diagrams or screen captures, in the form of a ZIP file that you can download and send to your localization provider.
section

Media Package

When you create a Media Package, all media files associated with your map are bundled into one ZIP file. The package contains only media files. No DITA maps or topics are included. The media files are located in a folder structure that is identical to your easyDITA folder structure.
The Media Package contains a folder named media-localization-package-number, for example media-localization-package-108 and at least one folder in which localization will be provided. This folder is named after the target locale, for example, the folder for Canadian French localization is named fr-ca, and the folder for Polish localization is named pl
section

Localization of Releases

In easyDITA, you can localize releases. Releases are a versioning tool that enables you to archive content at a specific point in time. The released version can then be downloaded, branched, published, and localized whenever you want.  
When you create a release, an archive of the content at its current state is created. The content that is archived in the release version cannot be modified. It is a permanent and unalterable archive. You can, however, continue to edit the original document normally.
For the released content, you can create all types of localization packages.
section

Localization of Branched Content

In easyDITA, you can localize branched content. Branches are a versioning tool that enable you to create a parallel set of content so you can edit the branched content without affecting the original content and push changes from one branch to another.
When a map is branched, full copies of each component are created in the new branch, along with its link dependencies. This allows you to edit the branched map without affecting the ‘original’ map. Then when you’re ready, you can merge or replace changes from one branch into another.
For the branched content, you can create all types of localization packages.

Media Package Localization Considerations

Make sure that your localization provider understand the structure of the Media Package and the basic rules of working with it.
section

Target Language Folder

Target language folder, for example, fr-ca or pl, is the folder your localization provider uses to localize content. When you create a Media Package, you select locales, that is target languages, for your localization job. For each of the locales, a separate folder is created in the Media Package. The folders are named after the names of locales, for example, the folder for Canadian French localization is named fr-ca, and the folder for Polish localization is named pl.
Each target language folder contains media files that are located in a folder structure that is identical to your easyDITA folder structure. Each target language folder also contains a manifest.xml file that contains a list of media resources and their destination in the package. For example:

< item resource-uuid="0d06da50-1169-11e6-9ac7-bc764e105744" resource-name="Classic_Toaster.jpg"         destination="media-localization-package-102/pl/master/documentation/documents/Instructive_Learning_and_Training/Demo_Content/Hardware/_Global_Media/Classic_Toaster.jpg"/> 

In this example you can see a media resource named Classic_Toaster.jpg and its destination in the folder structure, that is media-localization-package-102/pl/master/documentation/documents/Instructive_Learning_and_Training/Demo_Content/Hardware/_Global_Media/Classic_Toaster.jpg.

The manifest.xml file can be used by the localization provider to effectively navigate the folder structure of the Media Package and ensure all files are localized.
section

Localized Media Package

When the localization provider finishes the localization of your content, they send you the localized, zipped package that you can load to easyDITA. The ZIP file must contain all files and folders you sent to the localization provider and must be zipped correctly to avoid errors while uploading.

Creating a Media Package

When you create a Media Package for a map, all media files associated with the map, for example, diagrams or screen captures, are bundled together and made available to you in the form of a ZIP file that you can download and send to your localization provider.

The Media Package contains no DITA maps or topics, only media files. The files are located in a folder structure that is identical to your easyDITA folder structure.

prereq
Before you create a Media Package, verify that the media file names contain no illegal characters, for example, spaces. If they do, you will not be able to upload the localized package back to easyDITA.

  1. Create an Media Package for a map by doing one of the following: 

    Create the Media Package for a standard map: In the Content Manager , right-click the map for which you want to create the Media Package and click Localization Jobs .
    Create the Media Package for a released map:
    1. In the Content Manager , 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 Media 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 Manager , right-click the map and click Localization Jobs .

  2. From the New Localization Job drop-down menu, select Media Package . 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. 
    2. In the Manager field, leave your email address or change it to a different person.

      Step Information
      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 at hand.

    3. In the Include field, select All Media if you localize the files for the first time or Only Changed Resources if you have already localized the files.
    4. In the Pick Target Locales field, add a target language or more. 
    5. Click Save .
    Expected Result
    Your localization job displays. You can view the project notes, manager, locales, resources, and status of resources.

  4. Click New Localization Job and save the ZIP file to your computer. 

    Expected Result
    A ZIP file named media-localization-package-number.zip, for example media-localization-package-108.zip, is saved to your computer. The ZIP file contains all media files associated with your map. The files are located in a folder structure that is identical to your easyDITA folder structure. 

  5. Send your Media ZIP file to your localization provider.

    Step Information
    If your localization provider is not well familiar with localizing easyDITA Media Packages, share with them Localizing Media Content.

result
The localization process of your media content is now started.

Localizing Media Content

Localization is usually performed by an external localization provider. Sometimes, however, translators are available internally within the team. Regardless of whether you are a translator or you send your content for localization, you should know how to work with the Media Package when localizing content so that the package can be loaded back to easyDITA successfully.
  1. Save the ZIP file you received for localization to your computer and unzip it.

    Step Information
    Important: Do not change the name of the folder to which you unzip the file. Any modifications will cause errors when uploading the package back to easyDITA.

    Zipped and correctly unzipped media files:

  2. Open the unzipped Source Package folder and familiarize yourself with its contents:

    1. Navigate to a target language folder, for example fr-ca or pl, and open the manifest.xml file it contains.

      Step Information
      The manifest.xml file contains a list of media resources and their destinations in the package. Use it to effectively navigate the folder structure of the Media Package and ensure all files are localized.

  3. Navigate down the target language folder to media files and localize them.

    Step Information
    Important:Do not modify the file names, their extensions, or location. If you modify any of these, when uploading the ZIP file back to easyDITA, it will show errors and the upload will not be completed.

  4. When you finish localizing the media files, save them back to their original location under original file names and extensions.
  5. Zip the localized Media Package by right-clicking it and compressing it to a ZIP file. Name the new ZIP file exactly the same as the original ZIP file.

    Step Information

  6. Send the localized ZIP file back to the project manager or upload it to easyDITA.
result
The Media Package contains localization and is correctly compressed.

Uploading the Localized Media ZIP File

When your localization provider is ready with localizing your content, they send you an identical media ZIP file with the same content; the only difference is that the media files are now localized. Upload the ZIP file to easyDITA and verify if localization is complete.
context
  1. Upload localized content for a map by doing one of the following:

    Upload localized content for a standard map: In the Content Manager , right-click the map and click Localization Jobs .
    Upload localized content for a released map:
    1. In the Content Manager , 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 Manager , 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.

    Step Information
    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.

    Step Information
    After you upload your media ZIP file, all your media files should display as Current.

result
Your localized DITA content is now uploaded to easyDITA.

Viewing Localized Media Content

Locales are versions of your content in a target language, for example, in Canadian French or Polish. In easyDITA, you can easily view the locales for a map, topic, or media file in the Locales Tab. The locales listed are locales for the standard map and the locales created for the releases and branches of the map.
  1. In the Content Manager , navigate to the map, topic, or media file for which you want to view locales.
  2. Right-click the file and select Locales .
  3. In the Locales Tab, click the locale you want to view.

    Expected Result
    The preview of the locale displays.

result

Resending Media Content for Localization

After your localization provider returns your localized content, it may turn out it needs correction. In such a situation, you can resend it to the localization provider.
Note: If the localization job for your map is marked complete, create a new localization job and send it to the localization provider. See Creating a Media Package.
  1. Resend a map to the localization provider by doing one of the following:

    Resend a standard map: In the Content Manager , right-click the map and select Localization Jobs .
    Resend a released map:
    1. In the Content Manager , right-click the map and select Releases .

    2. In the Releases Tab, go to the release you want to localize and click Locales .

    Resend a branched map:
    1. From the Branch drop-down menu, select the branch that contains the map you want to resend.
    2. In the Content Manager , right-click the map and select Localization Jobs .
  2. In the Localization Jobs in Progress Tab, click the localization job that you want to resend to the localization provider.

    Step Information
    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 Download Localization Package, save the ZIP file to your computer and send it to the localization provider with instructions of what needs correction. 
result
Your content is sent for corrections to the localization provider. When you receive the corrected content, load it to easyDITA.

Downloading and Uploading Individual Localized Files

Sometimes, you may need to modify individual localized DITA or media files outside of easyDITA. You can do it from the Locales Tab.

Locales are versions of your content in a target language, for example, in Canadian French or Polish. The locales listed in the Locales Tab are locales for the standard map and for the releases and branches of the map.

  1. Download a localized DITA or media file to your computer:

    Download a localized file of a standard map:
    1. In the Content Manager , right-click the localized file you want to modify and select Locales .

    2. Select the locale, that is a target language, that you want to modify and click Download Locale . Save the file to your computer.

    Download a localized file of a released map:
    1. In the Content Manager , right-click the localized file you want to modify and select Locales .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, that you want to modify.

    4. From the list of localized files, click the one you want to modify.

    5. In the locale preview window, click Download Locale . Save the file to your computer.

    Download a localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized file you want to modify and select Locales .

    3. Select the locale, that is a target language, that you want to modify and click Download Locale . Save the file to your computer.

  2. Modify and save the file on your computer.

    Step Information
    Do not change the file name or extension. Otherwise, you will not be able to upload the file back to easyDITA

  3. Upload the updated file:

    Upload the localized file of a standard map:
    1. In the Content Manager , right-click the localized file you updated and select Locales .

    2. In the Locales Tab, click Upload Locale .

    3. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    4. In the Upload window, click Browse and navigate to the updated file. Click Open .

    Upload the localized file of a released map:
    1. In the Content Manager , right-click the localized file you updated and select Releases .

    2. In the Releases Tab, click Localize .

    3. Go to the Available Localizations tab and click show resources next to the locale, that is a target language, you updated.

    4. From the list of localized files, click the file you updated.

    5. In the locale preview window, click Upload Locale .

    6. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    7. In the Upload window, click Browse and navigate to the updated file. Click Open .

    Upload the localized file of a branched map:
    1. From the Branch drop-down menu, select the branch that contains the localized file you want to modify.

    2. In the Content Manager , right-click the localized topic that you updated and select Locales .

    3. In the Locales Tab, click Upload Locale .

    4. In the Pick Locale window, select the locale that you updated. For example, fr-ca for Canadian French or pl for Polish. Click Next .

    5. In the Upload window, click Browse and navigate to the updated file. Click Open .

result
The file with updated locale is now uploaded to easyDITA. Updates are displayed in the Locales Tab.