LocalizationX Document

Download and import the Example

1. Settings

Navigate to the main menu and select: Window > LocalizationX > Settings

• Scripts Output Folder: Stores exported C# scripts, including ID constants, Localization Components, and Localization API.
• Localization Output: Stores Localization Data, which should be inside the Resources folder for loading via Resources, or in the Localizations folder for loading via Addressable Asset System.
• Namespace: Defines the namespace for the exported C# files.
• Separate IDs: Sheets
  • TRUE: Exports [%IDs] sheets to individual C# files named [SheetName] + IDs.cs.
  • FALSE: Merges all [%IDs] sheets from all Excel files into a single C# file named IDs.cs.
• Separate Localization Sheets:
  • TRUE (default): Exports [Localization%] sheets to separate groups, each containing Localization Data, Component, and API, with the following file name structure:
    • Localization Data: [SheetName]_[language].txt
    • Component: [SheetName] + Text.cs
    • API: [SheetName].cs
  • FALSE: Merges all [Localization%] sheets from all Excel files into a single group, with the following file name structure:
    • Localization Data: Localization_ + [language].txt
    • Component: LocalizationText.cs
    • API: Localization.cs
• Only enum as IDs: For [%IDs] sheets, columns with the extension [enum] will be exported as enums and will not include the Integer Constant form.
• Language Char Sets: Used in Localization with TextMeshPro to compile the character table of a language, mainly applied for Korean, Japanese, and Chinese due to their extensive character systems.
• Google Client ID: Enter your Google Client ID (retrieved from Credentials in Google Console).
• Google Client Secret: Enter your Google Secret (retrieved from Credentials in Google Console).

2. Export from Excel Spreadsheets

Navigate to the main menu and select: Window > LocalizationX > Excel Spreadsheets

To manage complex Localizations across multiple Excel files, use this feature. It helps you handle and export all your Excel files with one click:

1. Add all the Excel files you want to process.
2. For each Excel file, you have the option to choose which sheets to include or exclude.
3. Click the Export All button to process.

3. Export from Google Spreadsheets

Prefer using Google Spreadsheets? No problem.

Navigate to the main menu and select: Window > LocalizationX > Google Spreadsheets

3.1. Setup Google Client ID and Client Secret

View instruction here

Copy the Client ID and Client Secret, and paste them into the corresponding settings in the Settings

3.2. Export Google Spreadsheets

Click on Add Google Spreadsheets, then enter the Google Sheet ID in the popup. Click Download, then select the sheets you want to process.

The Google Sheet ID is in the URL of the Google Sheet, like this:

https://docs.google.com/spreadsheets/d/[GOOGLE_SHEET_ID]/edit?......

4. Rules in Spreadsheet

4.1. IDs

Hero			Building			Pet			Gender[enum]
HERO_1	1	comment	BUILDING_NULL	0	comment	PET_NULL	0	comment	GENDER_NONE	0
HERO_2	2	comment	BUILDING_1	1		PET_1	1		GENDER_MALE	1
HERO_3	3	comment	BUILDING_2	2		PET_2	2		GENDER_FEMALE	2
			BUILDING_3	3		PET_3	3		GENDER_HELICOPTER	3
			BUILDING_4	4		PET_4	4
			BUILDING_5	5		PET_5	5
			BUILDING_6	6		PET_6	6
			BUILDING_7	7		PET_7	7
			BUILDING_8	8

ID Sheets, named with the suffix IDs are used to compile all IDs into Integer Constants. The design rules are:

• The sheet name must end with IDs.
• Only the Integer data type is allowed.
• Each group is organized in 3 consecutive columns.
• The first row contains the group name for easy reference.
• The first column holds the Key Name, and the next column holds the Key Value.
• Key Value must be an integer.
• By default, all IDs in a column will be exported as Integer Constants. Add the suffix [enum] to the group name to export them as an enum.
• To only export enums and skip Integer Constants, select Only enum as IDs in the Settings.

| Group | Key | Comment |
| ----- | --- | ------- |

4.2. Localization

idstring	relativeId	english	spanish
message_1		this is english message 1	este es el mensaje en ingles 1
message_2		this is english message 2	este es el mensaje en ingles 2
message_3		this is english message 3	este es el mensaje en ingles 3
content	1	this is english message 1	este es el mensaje en ingles 1
content	2	this is english message 2	este es el mensaje en ingles 2
content	3	this is english message 3	este es el mensaje en ingles 3
title_1		this is english title 1	este es el titulo 1 en ingles
title_2		this is english title 2	este es el titulo 2 en ingles
title_3		this is english title 3	este es el titulo 3 en ingles
whatever_msg		this is a sample message	este es un mensaje de muestra
hero_name	HERO_1	hero name 1	nombre del héroe 1
hero_name	HERO_2	hero name 2	nombre del héroe 2
hero_name	HERO_3	hero name 3	nombre del héroe 3

Localization Sheets are named with the prefix Localization and follow these rules:

• TThe sheet name must start with Localization.
• Each sheet has two key columns: the main key idString and an additional key relativeId.
• The following columns contain localized content.
• The key for each row is a combination of idString and relativeId.
• relativeId can reference an ID from the IDs sheets.

| idString | relativeId | english | spanish | japan | .... |
| -------- | ---------- | ------- | ------- | ----- | ---- |

5. How to integration

Download and import the Example

First, open the Excel file at /Assets/LocalizationX/Example/Example.xlsx. This file has example data to help you understand how to create Localization sheets

For the example using Google Sheets, you can view the file here.

5.1. Create folders for exporting files

Create 2 directories to store the files that will be exported:

• A folder to store the C# scripts (IDs, Localization Component, Localization API).

• A folder to store the Localization data.

  • There are two ways to set up the folder for Localization data, depending on how you want to load Localizations:
    • The easiest method is to load from the Resources folder. Create a folder inside the Resources folder to store Localization data. You can name this folder anything you like.
    • Alternatively, use the Addressable Asset System. In this case, create a “Localizations” folder outside the Resources folder and set it as an Addressable Asset. It’s recommended to name this folder “Localizations”.
• Navigate to Window > LocalizationX > Settings
• In Settings, set up the paths for the “Scripts Output Folder”, and “Localization Output Folder” using the folders you just created.

Create 2 folders:

• Assets\LocalizationXExample\Scripts\Generated: for C# scripts
• Assets\LocalizationXExample\Resources\Localizations: for Localization data

5.2. Scripting

• Initialization

LocalizationManager.Init();

• Change the language.

// Set the language japanese
LocalizationsManager.CurrentLanguage = "jp";

• Register an event handler for the language change event.

// Register an action when language changed
LocalizationsManager.OnLanguageChanged += OnLanguageChanged;

• You can retrieve localized content using three different methods.

  1. Retrieve localized content using a Key. Note that the text will not automatically refresh when the language changes using this method.

      // Retrieve localized text using an integer key
      m_simpleText1.text = LocalizationExample2.Get(LocalizationExample2.GO_TO_SHOP).ToString();
      // Retrieve localized text using an integer key with an argument
      m_simpleText2.text = LocalizationExample2.Get(LocalizationExample2.REQUIRED_CITY_LEVEL_X, 10).ToString();
      // Retrieve localized text using a string key with an argument
      m_simpleText3.text = LocalizationExample2.Get("REQUIRED_CITY_LEVEL_X", 25).ToString();
     

  2. Link a GameObject containing a Text or TextMeshProUGUI component with a key so that the text automatically updates when the language changes.

      // Register dynamic localized text using an integer key
      LocalizationExample2.RegisterDynamicText(m_dynamicText1.gameObject, LocalizationExample2.TAP_TO_COLLECT);
      // Register dynamic localized text using an integer key with an argument
      LocalizationExample2.RegisterDynamicText(m_dynamicText2.gameObject, LocalizationExample2.REQUIRED_LEVEL_X, "3");
      // Register dynamic localized text using a string key with an argument
      LocalizationExample2.RegisterDynamicText(m_dynamicText3.gameObject, "REQUIRED_LEVEL_X", "30");
     

      // Unregister the gameObject
      Localization.UnregisterDynamicText(m_textGameObject1);
      Localization.UnregisterDynamicText(m_textGameObject2);
      Localization.UnregisterDynamicText(m_dynamicText3);
     

  3. Using Localization Component.

     

Combine Localizations

If you want to combine all Localization Sheets, simply deselect the Separate Localization Sheets checkbox in the Settings. Next, delete all generated files and re-export everything.

Then, replace instances of LocalizationExample1 and LocalizationExample2 with Localization. Also, replace component LocalizationExample1Text and LocalizationExample2Text with LocalizationText.

Creating TextMeshPro Fonts for Different Languages

To create TextMeshPro fonts for Japanese, Korean, and Chinese, follow these steps using the respective character set files characters_set_jp, characters_set_ko, and characters_set_cn, which include all characters from the localization sheets:

Fonts to use in this example:

• Japanese: NotoSerif-Bold
• Korean: NotoSerifJP-Bold
• Chinese: NotoSerifTC-Bold

Creating TextMeshPro Fonts:

• For each language font, create a TextMeshPro font asset.
• Open the Font Asset Creator window in Unity.
• Under the Character Set section, select Character From File.
• Choose the appropriate character set file (e.g., characters_set_jp) in the Character File section.

Loading Localization Using the Addressable Assets System

To utilize this feature, follow these steps:

• Install the Addressable Assets System.
• Add ADDRESSABLES to the directives list in the Build Settings.
• Move the Localizations folder out of the Resources folder. Additionally, relocate the Output folder in the Settings.
• Set the Localizations folder as an Addressable Asset.