{"id":15160593,"url":"https://github.com/clpsplug/i18ntools","last_synced_at":"2026-01-20T20:33:58.097Z","repository":{"id":226209197,"uuid":"767805526","full_name":"Clpsplug/I18nTools","owner":"Clpsplug","description":"ClpsPLUG's I18n Tools for Unity","archived":false,"fork":false,"pushed_at":"2024-09-29T04:07:23.000Z","size":521,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"base","last_synced_at":"2024-10-17T14:11:21.779Z","etag":null,"topics":["internationalization","unity3d-plugin"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Clpsplug.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-05T23:34:15.000Z","updated_at":"2024-09-29T03:50:38.000Z","dependencies_parsed_at":"2024-04-18T23:36:26.434Z","dependency_job_id":"ad37c83e-aefc-4299-bedb-f589bc5e0e92","html_url":"https://github.com/Clpsplug/I18nTools","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"1458f7d01f767d1a46cf1fa4a1769e0b37c2c9a0"},"previous_names":["clpsplug/i18ntools"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2FI18nTools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2FI18nTools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2FI18nTools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2FI18nTools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Clpsplug","download_url":"https://codeload.github.com/Clpsplug/I18nTools/tar.gz/refs/heads/base","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247721928,"owners_count":20985083,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["internationalization","unity3d-plugin"],"created_at":"2024-09-26T23:03:12.842Z","updated_at":"2026-01-20T20:33:58.070Z","avatar_url":"https://github.com/Clpsplug.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ClpsPLUG's Internationalization Tools for Unity\n\nThis package enables internationalization of strings in Unity.\n\n## Installation\n\nUse UPM - select \"Add package from Git URL\" and paste the following:\n\n```\nhttps://github.com/Clpsplug/I18nTools.git\n```\n\n![add package](ManualImages~/upm.png)\n\n## How to use\n\n\u003e **Table of contents**\n\u003e 1. [Define the supported languages](#toc1)\n\u003e 2. [Define the \"strings\"](#toc2)\n\u003e 3. [Use the strings - the basic way](#toc3)\n\u003e 4. [Use the strings - the **easy** way!](#toc4)\n\u003e 5. [Change language](#toc5)\n\n### 1. Define the supported languages\n\u003ca id=\"toc1\"\u003e\u003c/a\u003e\n\nThis plugin looks for a JSON file at the following path:\n\n`Assets/Resources/I18n/SupportedLanguages.json`\n\nAnd the content of the file should look like this:\n\n```json5\n{\n  // NOTE: This example uses JSON5, but **an actual JSON CANNOT CONTAIN COMMENTS!**\n  // Start with the \"langs\" key\n  \"langs\": [\n    {\n      \"id\": 0, // ID to refer to this language\n      \"code\": \"ja\", // Code to be used in the string definition\n      \"display\": \"日本語\" // User-friendly text\n    },\n    {\n      \"id\": 1,\n      \"code\": \"en\",\n      \"display\": \"English\"\n    }\n  ]\n}\n```\n\nThe `code` value will be used as a key determine which string is for which language.\nIt can be those ISO 639-1 style codes like above, or you can even use locale codes like `ja_JP`.\n\nYou may add as many languages as you want - just make sure the `id` and `code` key do not collide.\n\n### 2. Define the \"strings\"\n\u003ca id=\"toc2\"\u003e\u003c/a\u003e\n\nThe i18n strings are provided through the following path by default:\n\n```\nAssets/Resources/strings.json\n```\n\nthe strings are defined in the following JSON format:\n\n```json5\n// NOTE: This example uses JSON5, but **an actual JSON CANNOT CONTAIN COMMENTS!**\n// The root element is always an array.\n[\n  // A regular string. Regular strings always have 'key', and codes from the supported languages definition as the keys.\n  {\n    \"key\": \"test\",\n    \"ja\": \"テスト\", // Japanese text, note that we use `ja` as key as we specified in the previous section.\n    \"en\": \"Test\" // English text\n  },\n  {\n    // Using \"_long\" variant enables you to write long text without having to add newlines.\n    \"key\": \"test-newline\",\n    \"ja_long\": [\n      \"改行付き\",\n      // Elements are joined by a newline (\\n).\n      \"テスト\"\n    ],\n    \"en_long\": [\n      \"Test with\",\n      \"a newline\"\n    ],\n    // Optional - set true to join string elements w/o newlines.\n    \"exclude_newline\": false\n  },\n  // You can also nest the strings to organize them better!\n  {\n    \"key\": \"parent\",\n    // Child strings are given with \"strings\" key, which takes an array.\n    \"strings\": [\n      {\n        \"key\": \"nested\",\n        \"ja\": \"ネスト\",\n        \"en\": \"Nested\"\n      }\n      // Of course, we can nest another resources.\n    ]\n  }\n]\n```\n\n### 3. Use the strings - the basic way\n\u003ca id=\"toc3\"\u003e\u003c/a\u003e\n\nThere are two ways to use the string - from the code, or as a static label in the scene.\n\n#### From the Code\n\nUse this syntax to get the string.\n\n```csharp\nusing Clpsplug.I18n.Runtime;\n\nstring i18nString = I18nString.For(\"key\");\n\n```\n\nThe `\"key\"` is replaced with the one given by your JSON string definition.\nFor example, if you want to show `Test`, you would write:\n\n```csharp\nI18nString.For(\"test\"); // returns \"Test\"\n```\n\nTo reach nested string elements, concatenate the keys with periods(`.`).\n\n```csharp\nI18nString.For(\"parent.nested\"); // returns \"Nested\"\n```\n\n#### As a static label\n\nYou want to grab either the `I18nStaticLabel` component or the `I18nStaticLabelUGUI` component\ndepending on which one you are using.\n\n* If you are placing the label in the world space, use `I18nStaticLabel`,\nas the GameObject in question shoudl have the `TextMeshPro` component.  \n* If you are placing the label as a UI element, pick `I18nStaticLabelUGUI`,\nas the GameObject in question should have the `TextMeshPro (UI)` component.\n\nThe component accepts 'key' as its parameter. \nSpecify the key from your JSON string definition and the string of matching language will be set to\nthe corresponding TextMeshPro component.\n\n![component screenshot](ManualImages~/component.png)\n\n### 4. Use the strings - the **easy** way!\n\n\u003ca id=\"toc4\"\u003e\u003c/a\u003e\n\nSpecifying keys is tedious. That's why we have editor tools!\n\nWe have two editor tools included:\n\n* I18n String Viewer\n* I18n Tools Window\n\nboth of which will be of great use.\n\nTo launch these, notice that your Unity Editor now has 'Tools \u003e ClpsPLUG' menu item - \ninside the 'I18n' menu, you will find those tools.\n\n#### The Tools Window\n\nThe tools window will be of big use when using the strings from your code.\n\n![Tools window](ManualImages~/tools.png)\n\nThis tool can perform two tasks: generate `I18nKeys` class and get characters used in your string resources.\n\nFirst, complete the path in the textbox so that it points to your string resource.\n\nThen specify the output file path (end it with `.cs`), provide optional class namespace,\nand click **Generate internationalization string class.**.\n\nThis will generate a file at the specified location that contains something like this:\n\n```csharp\n// Auto-generated by I18n Class Generator.\n// Any changes will be lost.\n// ReSharper disable InconsistentNaming\n// ReSharper disable UnusedMember.Global\n\nnamespace I18n\n{\n    /// \u003csummary\u003e\n    /// Members in this class can be supplied into \u003csee cref=\"ExplodingCable.I18n.Runtime.LocalizedString.For\"/\u003e parameter.\n    /// \u003c/summary\u003e\n    public static class I18nKeys\n    {\n        /// \u003csummary\u003e\n        /// ja: テスト\u003cbr/\u003e\n        /// en: Test\u003cbr/\u003e\n        /// \u003c/summary\u003e\n        public const string test = \"test\";\n        /// \u003csummary\u003e\n        /// ja: 改行付き テスト\u003cbr/\u003e\n        /// en: Test with a newline\u003cbr/\u003e\n        /// \u003c/summary\u003e\n        public const string test_newline = \"test-newline\";\n        public static class Parent\n        {\n            /// \u003csummary\u003e\n            /// ja: ネスト\u003cbr/\u003e\n            /// en: Nested\u003cbr/\u003e\n            /// \u003c/summary\u003e\n            public const string nested = \"parent.nested\";\n        }\n\n    }\n}\n\n```\n\nThese static classes and members can be directly supplied into the `I18nString.For()` method,\ngreatly reducing the risk of typo.\n\n```csharp\n// instead of writing this...\nI18nString.For(\"parent.nested\"); // returns \"Nested\"\n\n// write THIS!\nusing I18n;\nI18nString.For(I18nKeys.Parent.nested); // also returns \"Nested\"\n```\n\nThe second button, **Get characters used in the strings asset**, \nis most useful for TextMeshPro's Font Asset creator.  \nSince languages such as Japanese have extremely wide range of possible characters to appear,\ncontaining them all would be a bad idea as it bloats your final game size.\n\nWhen you click this button, the tool will scan for characters used in your string resource,\nand packs them as a string, which appears below.  \nThis string can then be clicked and \"Select All\" (Cmd-A, Ctrl-A) and \"Copy\" (Cmd-C, Ctrl-C)\nand pasted directly into the font asset creator.\n\n\u003e [!NOTE]  \n\u003e A few characters will be implicitly added to avoid TextMeshPro warnings.  \n\u003e You can also check \"Include numeric (and related) chars\" to include such chars\n\u003e without having to manually specify them in your string resource.\n\n#### The String Viewer\n\nThis string viewer lets you see the string resource in a tree view!\n\n![Strings viewer](ManualImages~/viewer.png)\n\nFirst, complete the path in the textbox so that it points to your string resource.\n\nSelect a row from the list and click **Copy full key of selected element** \nto copy the \"full key\" of the string to the clipboard.\nThis value then can be used to paste into \nthe `I18nStaticLabel` component or the `I18nStaticLabelUGUI` component.\n\n\n### 5. Change language\n\u003ca id=\"toc5\"\u003e\u003c/a\u003e\n\nTo change the language, we need to use the `id` value from the supported languages definition (see [Section 1.](#toc1)).\n\nOnce you have implemented the language selection screen, those are the methods you want to run.\n\n```csharp\nusing Clpsplug.I18n.Runtime;\n\n    int lang = 0 /* language choice */\n    \n    I18nStringRepository.GetInstance().ChangeLanguage(lang);\n    I18nTool.NotifyLanguageSwitchToStaticLabels();\n```\n\nThe first method, `ChangeLanguage(lang)`, changes the strings returned from `I18nString.For`\nto the specified language.  \nThe second method, `I18nTool.NotifyLanguageSwitchToStaticLabels()`, triggers a refresh for \nall the GameObjects with either the `I18nStaticLabel` component or the `I18nStaticLabelUGUI` component attached\nso that their text turns into the string of the specified language.\n\n# TODO\n\n* More documentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclpsplug%2Fi18ntools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclpsplug%2Fi18ntools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclpsplug%2Fi18ntools/lists"}