Chunks Used in Chat #5

### **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?**

Creating a Chapter Set When you’ve created all your configurations, you can go ahead and create your Chapter Set. Chapters Sets are the container where you’ll find all your levels.  1. Navigate to **Levels & Chapters \> Chapter Sets**. A table is shown with all the existing Sets, their availability and where they’re being used. Click **[+New]** to create a new Set. 2. Name your Chapter Set, and start configuring the Chapter Structure: **About Mass Operations** The Mass Operations button allows you to: - Copy chapters from one Chapter Set to another - Batch update Chapters **Keep in mind that only the changed fields will be applied and overridden.** - Change the status of test Chapter Sets to Live **Chapter Sets & Layout Banks Validations** - Editing Layouts is **not allowed** when they are being used in Chapter Sets. To make any modifications, create a new entity (or duplicate) and then choose it in the Chapter Set. - Note that you must have editor privileges on the layout bank page to make any edits. Also, you cannot alter a layout bank that has already been used. - Make sure that that each level is given a unique name, and that the level is marked as "valid for use" with a value of "true." Failure to do so will result in the level not being displayed in the list of available layouts for Chapter Sets. ## Enabling your Chapter Sets in Game Settings Once you’ve configured your Chapter Sets, it’s time to enable them in Game Settings so that they can be sent to players.  To do so, navigate to Game Settings, and click the green plus button to enable Chapter Sets. Once done, select your Chapter Set from the dropdown.  Chapter Sets are A/B testable entities, which allows you to create experiments with them. Read more about A/B Experiments [here](/wiki/spaces/KB/pages/2581889051/Setting+up+A+B+Experiments). ## Comparing Configurations The configuration inside Chapter Sets can be compared using the Comparison Tool. This tool compares 2 different entities, highlighting differences and underlining where these differences are.  To use this tool, follow the steps below: 1. Navigate to Chapter Sets, and click **[Compare]** on the upper right corner of the screen: 2. Select the entities you’d like to compare, and click the blue compare button  3. A new screen will appear where the differences will be highlighted: The Comparison Tool is available for the following entities: - Chapter Sets - Scrapbooks - Picture Banks ## Download Layout Banks & Chapter Sets JSON File This section explains how to download a level layout bank and chapter sets file sfrom Game Server for review, backup, or transfer. Use the table’s Actions column to export the selected bank. ### Download **Layout Banks/Chapter Sets File** 1. From the top-left app switcher, choose the relevant game (e.g., _TripleTile_). 2. Go to Layout Banks: Levels & Chapters → Layout Banks. 3. Find the relevant bank: use Filter (top bar) or page through the list. 4. In the actions column of the bank row, click the Download icon (↓). Your browser will download the bank file (usually JSON/CSV; format depends on the bank). 5. To download a chapter sets file, go to chapter sets: Levels & Chapters → Chapter Sets. 6. Repeat the steps 3 and 4 above to download a chapter sets file. ### Upload a Level Layout Bank (via **Upload file** ) Import a whole level bank (with all its layouts) from a JSON/CSV file. 1. Navigate to Layout Banks. 2. Click the green Upload button. 3. In the file picker, select the json/csv file and click **Open**. 4. The bank is created/imported. You’ll be returned to the Layout Banks table. 5. Find the new bank at/near the top of the list (check Updated at time). 6. Click the bank name to open View Layout Bank. 7. (Optional) Adjust details:  ## Create Chapter Sets from a CSV This section explains how to create/update Layout Banks and Chapter Sets from a CSV file. ### CSV Format Fields marked **optional** should only be included if the script requires them for your game. | **Column** | **Required** | **Type / Validation** | **Notes** | | **Level\_ordinal** | Yes | Integer, min 1 | The absolute level number in the target Chapter Set (no upper limit). | | **Level\_hash** | Yes | Non-empty | Hash used to look up an existing Level Layout. | | **Origin\_layout\_bank\_id** | Yes | Integer, non-empty | ID of the existing Layout Bank from which the Level Layout is copied. | | **New\_layout\_bank** | Yes | String, unique per new bank | Name of the destination Layout Bank to create/apply in the duplicate Chapter Set. | | **Level\_position** | Optional | Integer, min 1 | Position within the Layout Bank (use only if required by script). | | **Chapter\_position** | Optional | Integer, min 1 | Chapter index in the Chapter Set (use only if required by script). | ### _ **Create new chapter set from .csv** _ 1. In GS, select the correct environment (Staging or Production) and the correct Application. 2. Go to Levels & Chapters: Chapter Sets. 3. Click Create new chapter set from .csv. 4. On the Create Chapter Set from CSV screen: 5. Click **Upload** to run validations and start the script. 6. Watch the Script Log: - The Script Log shows parsing, validation results, and progress. - If there are validation errors, the log will list the rows with issues; fix your CSV and re-upload. - If all checks pass, the script will create/reuse Layout Banks, duplicate the selected Chapter Set, and apply levels.  ### What the script does 1. Create new Layout Banks for every unique New\_layout\_bank in the CSV only if they differ from the referenced origin layout bank content. 2. Reuse existing Layout Bank (from Origin\_layout\_bank\_id) if there are no differences vs. the CSV. 3. Duplicate the selected Chapter Set with the provided New Chapter Set Name. 4. Apply Layout Banks to the correct positions in the duplicated Chapter Set. 5. Place levels into those banks based on Level\_ordinal (and Level\_position if used). * * * ### Post‑upload verification 1. In Chapter Sets, open the newly created set by name. 2. Confirm new Layout Banks were created only where changes exist; unchanged segments reuse origin banks. 3. Check level counts, ordering (by Level\_ordinal / Level\_position), and layout types. 4. Smoke test any downstream visuals/themes/goals that depend on layout type.