### **Introduction**

In this article you’ll learn about:

- How localisations work in Harmony

- Editing, adding or deleting your localisations

**Table of Contents**

* * *

**The Localisation Service is now Available in Harmony**

Localisations is now accessible through the following URLs:

- **Staging** : [https://harmony-staging.tripledotapi.com/admin](https://harmony-staging.tripledotapi.com/admin)

- **Production** : [https://harmony.tripledotapi.com/admin](https://harmony.tripledotapi.com/admin)

# What is Localisation?

Localisation is the process of translating and adapting a product to a local market. Localisation goes beyond simply translating the text, as during the localisation process, dates, currencies and general content is adapted to a specific audience.

Localisation is key for a growing business, as it increases the potential to get more players and increase the revenue.

Through Harmony, you can manage the localisation of your game.

# Managing Localisations in Harmony

Harmony is the container to centralise and unify all Game Server and Hawk Applications. In there, you’ll be able to find the applications for your games.


To access the Localisation Service for your game:

1. Access Harmony, and click your game in the home page

1. On the left side bar, click the drop-down on Localisations to open all the settings available

In the dropdown menu, there are four items available:

- **Languages** : the list of languages available for translation in your game

- **Translations (Live)**: read only page where you can see which translations are currently live

- **Translations (Test)**: page where you can upload your translations and test them in a test environment

- **AI Translations** : page where you can utilise AI assistance for your translations

**Settings Config** is still available in Game Server
Languages

Inside Languages, you can visualise the list of languages configured in Settings for your game. English is the source and default language and it cannot be deleted.

The **In Use** column allows you to see in which configuration this language is being used.

### Adding a New Language

1. To add a new language, click the **[New]** button on the upper right side of the screen. A new pop-up will open with a dropdown list of languages.

2. Select your language from the dropdown list. You can also search by name or language code.

3. Click **[Save].**

## Translations (Test)

From this section, you can:

- Manage your existing translations

- Download translations in CSV format

- Download translations from AI

- Preview and test your translations in a test build

- Search and filter

### Adding New Translations

There are four ways to add new translations:

- Manually

- Via a CSV file upload

- With AI Assistance

- Via internal API

### **Adding a new key manually**

1. Navigate to **Translations (Test)** and click **[Add Key]** button.

2. Add a unique name for your key, select the type of content and add a description.

3. Under _English EN_, type in the English source text. Click **[Add]**.

4. A new table named **Changed Keys** will appear. From there you can add your translations manually or make changes. The system will highlight in yellow your changes.

5. Once you’re done, click **[Save].** Your localisation will be uploaded and testable in a test build.

6. When your translations have been tested in a test build, you’ll be able to push them to Production. Read [Applying your localisations to live](https://tripledotstudios.atlassian.net/wiki/spaces/KB/pages/3230760961/Managing+Localisations+in+Harmony#Translations-(Live)---Applying-your-localisations-to-Live) to know more.

### Editing your Translations

From **Localisations: Translations (Test)**, you can also edit your translations and their description.

1. Double-click on the text you’d like to edit. An editable field will appear so that you can amend your translation

2. A new table will appear above with the changes highlighted **in green**. Review them and click **[Save]**. Please note that these changes **will be applied only to your test environment.**

3. If you’d like to apply your changes to Live, click **[Review Difference].** This button will be active only if you clicked **[Save]** before.

4. Review the changes, and click **[Apply to Live]** to push your changes to Production. Changes will be highlighted in green.

#### Deleting and Undoing Changes in your Translations

If there’s any edited key you don’t want to apply to live, you can undo the changes using the **[yellow undo button]**


In **Translations (Test)**, you can delete keys by using the red Trash Can button, but if you mistakenly delete a key, you can use the **[undo button]** to recover them:


### Uploading a CSV file with Translations

The CSV upload feature allows you to bulk upload a series of translations in different languages.

1. To upload a CSV, navigate to **Translations (Test)** and click **[Upload CSV]**

1. Upload your CSV file. The CSV upload allows you to:

- Add keys & translations

- Add and update translations for existing keys

  **Which format should my CSV file have?**

The format of the CSV file must have the following fields:

- Key

- Type

- Desc (description, the field can be empty)

- Language codes following ISO-639-1 convention (2 letters/2 letters + locale, for example: `pt-BR`)

**Other Considerations**

- The **[CSV Upload]** button might be disabled. To enable it, please apply a change manually beforehand.

- The CSV file **must** be UTF-8 encoded

- Any new language must be created manually in the Languages section in advance. If the language does not exist, the upload will fail.

- Sometimes Excel/Google Spreadsheets add quotation marks at the start of your CSV file. Please remove them if this happens, as this will cause the upload to fail

4. Once your translations have been tested in a test build, you’ll be able to push them to Production. Read **Applying your localisations to live** to know more.

If there is any validation error in your uploads, you can use the checkbox **Show only keys with validation errors**. This checkbox appears only if there are any validation errors to review after clicking **[Save]**, and it will mark in red your errors for better visualisation and more efficient error fixing.


### Downloading Translations

You can download the translations in CSV format on your local system.


**Generating AI Translations**

The AI Translations feature enables users to automate the translation of key text fields within the system.

You can generate translations for multiple languages directly from the interface.

1. Go to the _**Translations (Test)**_ Page.

2. Click on **[Download with AI]** to open the translation request popup.

3. Select Target Languages:

4. Click **[Confirm]** to send the request to AI.

After clicking the **[Confirm]** button, new translations will be generated shortly. A message appears: "Operation has been successfully finished."
You can track the progress on the AI Translations page.

### **Accessing the AI Translations Page**

The AI Translations page lists all the translations generated using AI. You can track the progress of the requested AI-assisted translations from the same page.

1. From the left sidebar, go to Localisations \> AI Translations.
The page displays a table with the following columns:

### **Downloading AI Translations**

1. Locate the file in the AI Translations table.

2. If the status is "Generated", click the Download button.

3. The CSV file will have the same format as the current Download/Upload feature, making it easy to update localisations.

If the CSV file is not getting downloaded for updating localisations, try the following step:

Right-click the **Download** button and click the **SaveLink As..** option. The file will be saved at the required location and you can update the file.

.png?version=1&modificationDate=1748873604575&cacheVersion=1&api=v2&width=777&height=207)
### **Deleting AI Translation Files**

1. In the AI Translations table, locate the file.

2. If the status is _"Generated", “Scheduled”,_ or _"Failed"_, the delete button is available.

3. Click the **delete** icon to remove the file. You will receive a confirmation pop-up for deleting.

## Translations (Live) - Applying your localisations to Live

To ensure quality and consistency among localisations, Harmony first uploads the localisations in a test environment, and **once that they’ve been verified, they can be pushed to a live build.**

1. Under **Translations (Test),** you’ll find a button called **[Review Difference].** This button opens a panel where you’ll visualise the changes made since the last push to live. The date of the last push to live can be found on the upper right side of the page.

2. Review the changes and click **[Apply to live]**. Lines marked in green show the new keys that have been added. The changes will then be pushed to Production, and you’ll be redirected to **Translations (Live)**, a read-only page where you’ll be able to visualise what is currently in Production. During this process, if there are any keys to be deleted, they will be deleted too.

If there are no differences between Test and Live, you’ll be shown a message stating this.


Any change that you’d like to make to your translations needs to be done through **Translations (Test)** and pushed to Production through the **[Apply to Live]** button. You can only download translation files or apply filters on the **Translations (Live)** page.

* * *

## Using the Internal API

The Localisation API allows you to programmatically interact with the Localisation App to synchronise localisation data, visualise and export localisation keys and languages and their statuses.

To use the API:

1. Authenticate with your personal token ([obtained from your personal profile in SSO Server](/wiki/spaces/KB/pages/3292790799/Generating+SSO+User+Tokens))

2. Get your `app_id`, which is the unique identifier of your game. For more details, see [this Confluence page](/wiki/spaces/GS/pages/3122561158/Public+App+IDs).

3. Use the following endpoints: [https://backstage.tripledotapi.com/catalog/localisations-server/api/internal/definition](https://backstage.tripledotapi.com/catalog/localisations-server/api/internal/definition)

* * *

## Settings Configs

Settings Configs is available in Game Server

In the section Settings Configs, you’ll find the configurations for localisations in Game Settings. The column **In Use** allows you to see in which Setting this particular configuration is being used.

#### Creating a New Config

When you create a new localisation Config, you can edit the language settings for the game, including the default language, the languages supported by the game, and the order of the languages in the pop-up when selecting them.

1. Click the green **[+New]** button on the left upper corner.

2. Add a new name for your Config.

3. Under Languages supported by the client, you can add the languages you want the game to support. The default configuration is presented below, but you can add as many languages as you need using the dropdown and clicking **[Add]**.

4. Under Client Default Language, you can modify the language presented to the player when opening the game.

5. You can also select whether you want to send a pop up to the player when they open the game, and order the list of languages presented. The list is presented in the current state, so drag and drop to organise, or move to the **Removed** section to remove languages.

6. Once you’re happy with the settings, click **[Save]**.

#### Using your Config in Game Settings

Once you’ve created your Config, you can include it in Base Config, Overrides or A/B Experiments.

Simply enable the field, select your Config, and click **[Save]**.

* * *

## Localisations in Hawk

Some features in Hawk, such as Campaigns and App Links can be localised. Localisations are synchronised **every hour** with Hawk, but you can force this process too.

### Synchronising Localisation Keys with Hawk

In order to add localisation keys for Hawk:

1. Add your localisation keys to Localisation App as described in this guide.

2. Navigate to **Hawk \> Localisations**. A page will open with the existing keys, their usage, and the last synchronisation date. As stated above, localisations are synchronised hourly with Hawk, but you can force this process by clicking the **[Synchronize]** button on the upper right corner.

3. Once your keys have been synchronised, they will be available to be used in any Hawk feature that allows localisation.

* * *

## Localisations FAQ

- **What happens if a translation is missing in a target language?**

- **Can I use emojis in localisations?**