---
title: "Localization"
canonical: "https://help.agiloft.com/space/HELP/43714487/Localization"
format: markdown
---
Agiloft supports international language localization. This article introduces you to the translation process in Agiloft and provides instructions for localizing the text in different areas of the system. 

> 📝 If you're looking to translate your system to French, German, Brazilian Portuguese, or Spanish, use the User Menu > Language drop-down to select the language and see if your KB already offers that translation. If it doesn't, contact Support to acquire the latest version of the Agiloft-supplied language files. This can save you time and effort by minimizing the number of terms you need to translate.

# How the Localization Process Works

Fully translating the user interface involves translating strings in three areas of the system: the Power User Interface (PUI), End User Interface (EUI), and system administration or server-level area. Each area is represented by a file that stores localized versions of each string.

- PUI-level text: Text shown in the Power User Interface that is KB-specific, including out-of-the-box and custom table and field names, actions and action buttons, saved searches, group and team names, rule descriptions, and so on. In most cases, this includes any entity in your KB whose name you can set or edit.

> ℹ️ Agiloft supports machine translation of Power User Interface text using the [Google Cloud Translation API](https://docs.cloud.google.com/translate/docs). For more information, see [Google Translate for Localization](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/639107085).

- EUI-level text: Text that is specific to your EUI, like home pages, headings, menus, hyperlinks, and forms.
- Server-level text: Text that is universal to all KBs on the server, like the admin setup menu, setup wizards, save and cancel buttons, and error messages.

> ⚠️ Because server-level text applies to all KBs on the server, you must have administrative access to the server to add a translation file. For hosted or shared servers, contact Support for information about providing or collaborating on server-level localization for your target language.

## How Translations are Stored

Translatable text for each type of user interface is stored in a separate file or record. You can download the files from your KB, localize them following your own translation and approval processes, and then upload the translated files back to the KB. Once the files are uploaded, you can enable the new language for teams so those users can select that language from their Language menu.

The list below describes the translation files.

- **User Translation File**: This file stores Power User Interface translations. It’s a UTF-8-encoded plain text file, named <Language>.txt, that defines the user-facing strings in the Power User Interface. You can download the file, send it for translation, and then upload it back to the KB, or you can set up [Google Translate](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/639107085) integration to automatically generate machine translations at the point of download, so you only need to review the file and then upload it.

> ℹ️ When adding a new language to a system, using Google Translate can be more time- and cost-effective. When adding fields, saved searches, and other entities in the future, you can set up Google Translate to automatically translate new text as the entities are added. Generally, the in-system review workflows are more user-friendly than working with the translation files.

- **EUI Templates Translation Properties**: For EUI-level translations, user-facing strings are defined in a translation.properties record in the EUI Templates table. There is one translation.properties record per language.
- **Program Translation File**: This file stores the system admin or server-level translations. It’s a properties file, named GUI2_<java_locale>.properties, that defines the user-facing strings for all systems on the server. Because the file applies to all KBs on the server, you can’t upload program translation files unless you have admin access to the installation directory on the server.

Each line in a translation file or record is a key=value pair, where the key is the identifier for the item in the application, and the value is the text displayed in the user interface for that item. 

> ℹ️ **Example**
> ℹ️ 
> ℹ️ In the User Translation File, you can find field label definitions like `tables.contract.columns.budget_amount.label=Budget Amount` for the Budget Amount field in the Contracts table, rule descriptions like `tables.contract.rules.d0fda6bfac1e12da311145974525c72f.description=TB: Activation, Expiration and Termination Actions`, and choice list values like `tables.contract_clause_source.choices.1.value=Document Template` and `tables.contract_clause_source.choices.2.value=Added from Library`.

Instructions for [downloading](#) the files, working with each file, and uploading the files back to the system are included in later sections in this article. 

### What’s Not in the Translation Files

The Power User Interface localization file, User Translation File, doesn’t include all of the data in your KB. This section describes what isn’t included in the file.

- The file doesn’t contain any record data, including email templates and contract clauses that are stored in records. You can translate records as needed by editing them directly or by copying them to create language-specific versions of the record. For example, you can clone [Clause Library](https://agiloft-public.atlassian.net/wiki/spaces/SD/pages/44434075) clauses and indicate which clauses have multiple languages available.
- The file also doesn’t include contract documents, document templates, and other attached documents. You can translate these items as needed by downloading the files and then uploading translated versions.
- The file might not include many of the choice values from choice lists. For localizing choice lists, you can use a translate-as-you-go approach. To do so, select the target language from the Language menu drop-down in the upper right, then go to **Setup › System › Manage Choice Lists**, edit the list you want to translate, and make your changes. The changes you make are stored in the appropriate language file. For more information, see [Translate as You Go](#translate_as_you_go) below.
- The file doesn’t include the KB name.

## How to Make Future Updates

Once you’ve added a new language, there are a few options for making updates to translation files after further customizing the KB and creating new entities.

- You can translate strings directly in the user interface while editing new entities. For details, see [Translating an Item Directly in the Power User Interface](#translate_as_you_go). This is useful if your administrators perform your translations or if you use [Google Translate](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/639107085) to automatically translate new text as entities are added.
- If your translations need to go through a separate process and there isn’t heavy overlap with your admin team, you can download the User Translation and Program Translation files with the “Hide fields that have already been translated” option enabled so only new, untranslated strings are included in the files.

# > Macro (anchor)

Downloading the Translation Files

To access the EUI Templates translation properties:

1. Go to the EUI Templates table and open the `translation.properties` record.
2. Copy all of the text in the Body field.
3. Paste the text into a plain-text editor, such as Notepad++.
4. Save the file as `translation_xx.properties`, where `xx` is the java locale for the selected language. For example, a German translation file would be saved as `translation_de.properties`.

To download the User Translation File and Program Translation File:

1. Go to **Setup > Localization**.
2. On the Language tab, select the target language from the drop-down list. Click Next.
3. On the Table tab, select the tables you want to include in the translation file. Table names appear in red when there is no available translation. By default, Table Tree at the top of the screen is selected, including all tables in the system. To translate the text in a specific table, highlight the table name you want to translate. Click Next**.**
4. On the Options tab, choose whether to exclude previously translated text by selecting or clearing the “Hide fields that have already been translated” checkbox. Click Next**.**
5. On the Translate tab:
  - If you want to use Google Translate for the language you selected, select Machine Translate now and download the `<Language>.txt` file. The system runs the content through Google Translate and applies the machine translations to the file before you download it, so the downloaded file contains a full machine-translated dictionary for the language, which you can manually review and edit before uploading it to the system. You must [set up Google Translate integration](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/639107085) for this option to appear. If you have set up Google Translate integration and the option is not available, go back to your Google Translate configuration and make sure the language is selected in the list.
  - If you don't want to use Google Translate, click the file link under User Translation File to download the file.
6. If you want to localize the server-level text, download the `GUI2_xx.properties` file as well. If you want all new KB created on your server to include the localization file, translate the default Demo KB. New knowledgebases are created based on the Demo template.

# > Macro (anchor)

Localizing the Power User Interface

Edit the file `<Language>.txt` file that you [downloaded](#). The file contains key=value pairs, where the key identifies an entity in the KB, and the value is the user-facing string for the entity. The file is stored in UTF-8 encoding and can be edited in any program that supports that encoding. When you've translated the values, follow the steps below to apply your translation to the system.

> ℹ️ Make sure the translations in the file are reviewed and approved before uploading the file. Uploading a file automatically marks all the translated content as Translation Approved for the [Google Translate review tool](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/639107085).

1. Go to **Setup > Localization**.
2. On the Language tab, select the language you want to update.
3. Navigate to the Translate tab.
4. Click Browse... to find and select your file, then click Upload.
5. Save your changes.

The localization file is stored in your KB only and does not interfere with other KBs on the same server. This file is retained even if the KB is re-imported or copied.

> ⚠️ Remember that Power User Interface text doesn’t include all the text you see in the system. Error messages and text in admin setup wizards is maintained at the server level and controlled by the [Program Translation File](https://agiloft-public.atlassian.net/wiki/spaces/hdrafts/pages/edit-v2/44009534#SystemProperties).

## > Macro (anchor)

Translating an Item Directly in the Power User Interface

You can translate an individual item using setup menus. This workflow is designed for admins working in the language who spot an untranslated item and want to provide a translation on the spot.

> ℹ️ [Google Translate Integration](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/639107085) provides dedicated workflow options for translating new tables, fields, and other system entities.

To translate an individual item:

1. Select the target language from the Language menu drop-down in the upper right. For example, if you want to provide a French translation for an English item, choose French.
2. Navigate to the setup wizard for the item you want to translate.
3. Enter the translated values for the label.
4. Save your changes.

You can use this method to translate items that get included in the User Translation File, like table and field labels, choice list items, saved search and rule descriptions, and so on. The changes you make are stored and kept in the appropriate language file for the KB.

# Localizing the End User Interface

Open the file `translation_xx.properties` file that you created when you copied content from the translation.properties record in the EUI Templates table. The file contains key=value pairs, where the key identifies an entity in the EUI, and the value is the user-facing text for the entity. The file includes comments that describe each section of string definitions. At a minimum, to provide a translated interface, translate the items under the heading `#These variables provide the text on the home pages`. You can also show or hide tables and menus for a language, define specific home and search pages, or define localized name values in any combination, but make sure those settings are appropriate to be tied specifically to the selected locale.

When you've translated each value and made any other desired changes, follow the steps below to apply your translation to the system:

1. Go to the EUI Templates table.
2. Select the checkbox next to the `translation.properties` record.
3. Select **More **> **Copy**.
4. When prompted, name the record `translation_xx.properties`, where `xx` is the java locale for the selected language. For example, for Danish, add `_da` after `translation`.
5. Click Finish.
6. Open the new record.
7. In the Description field, replace English with the appropriate language.
8. In the Body field, delete all the text. Then, paste the text from your completed translation file into the field.
9. Click Save.

EUI translation properties are stored in your KB only. They don’t interfere with other KBs on the same server. The record remains in the KB after reimport and when copying the KB.

# > Macro (anchor)

Localizing Text at the Server Level

> ⚠️ Remember that uploading the system properties file requires server-level admin access to the installation directory. We recommend contacting Support to assist you.

The system admin or server-level localization file, Program Translation File, is a property file that contains key=value pairs, where the key identifies the property in the application, and value is the user facing string for that property. If you want to correct a particular field name, label, or phrase, but you can't find it in the file, you can get an English translation file, search it for your phrase, and note the property key. Search for the property key in the localization file to find the phrase you need to correct.

Most files contain many properties with duplicate names. We have a special script called `collapse_stringlist.pl` to simplify the translation procedure for duplicates.

In Agiloft, the base (English) file for internal program strings is called `GUI2.properties`. Let's say, for example, you wish to translate this into the Latin language using a UTF-8 text editor. After obtaining the base file from Agiloft, prepare it for translation using the command:

```
collapse_stringlist.pl -v GUI2.properties > AL-latin.txt
```

After translating all of the strings in `AL-latin.txt` using your text editor, run the following command to import the translation to the properties file:

```
collapse_stringlist.pl -v -i GUI2.properties AL-latin.txt > GUI2_la.properties
```

Now you can add the file `GUI2_la.properties` to Agiloft and select the Latin language from the GUI.

If, after the original translation, you upgrade to a different version of Agiloft, obtain the list of new strings to translate using the command:

```
collapse_stringlist.pl -v GUI2.properties AL-latin.txt > AL-latin-2.txt
```

After translating the strings in `AL-latin-2.txt`, import using the command:

```
collapse_stringlist.pl -v -i GUI2.properties AL-latin.txt AL-latin-2.txt > GUI2_la.properties
```

#### Unicode Encoding

If the translated file is in the UTF-8 encoding, which most customers send to us, it's easy to convert it to unicode format using the Java utility native2ascii. For example: 

```
native2ascii -encoding utf8 SpanishUTF8.txt Spanish.txt
```

#### Partial translation

If you created a KB-specific localization file – for example, `French.txt` with "Hide fields that have already been translated" enabled – and you want to replace parts that haven't yet been translated by already translated parts in another file, we have a special `translation_merge.py` script to do it.

```
translation_merge.py <A> <B> <C> <output_file>
```

**Input parameters and Output:**

|  |  |
| --- | --- |
| Translation file A | English translation file for KB 1 |
| Translation file B | Foreign language translation file for KB 1 |
| Translation file C | Foreign language translation file for KB 2.<br>Note: It may be partially translated already, but it contains some strings that have not been translated. |
| Standard Output | Foreign language translation file for KB 2. a New_translated_file to standard output |

> ℹ️ **Example**
> ℹ️ 
> ℹ️ translation_merge.py KB1_english_file.txt KB1_french_file.txt KB2_french_file > New_translated_french_file

> ❌ If you upload a customized file directly into your system, it will be overwritten with future text changes and fixes from Agiloft. Please send your localized GUI2_xx.properties file to Support after translation so it can be included in a future release build. Submit a ticket through the [Support Portal](https://www.agiloft.com/support-login.htm) with the localized GUI2.properties file attached after the translation has been completed.

#### Related articles

> Macro (contentbylabel)