--- title: 'i18n Plugin (Internationalization)' url: 'https://www.twelvetone.tv/docs/developer-tools/intellij-plugins/i18n' markdown: 'https://www.twelvetone.tv/docs/developer-tools/intellij-plugins/i18n.md' date: '2026-09-25' description: 'A tool for managing i18n translations in IntelliJ' taxonomy: category: - docs devtype: - cc --- [](#) [ Home ](https://www.twelvetone.tv/docs/) [ Developer Tools ](https://www.twelvetone.tv/docs/developer-tools) [ IntelliJ Plugins ](https://www.twelvetone.tv/docs/developer-tools/intellij-plugins) i18n Plugin (Internationalization) This product is in active development and has been released under the [Creative Commons license](https://creativecommons.org/licenses/by-nd/4.0/). A tool for managing i18n translations in IntelliJ #### Table of Contents - [Overview](#overview) - [Roadmap](#roadmap) - [Source Implementation](#source-implementation) - [Data Store Implementation](#data-store-implementation) - [Configuration](#configuration) - [Configuration Settings](#configuration-settings) - [Example Configuration (i18n.config.js)](#example-configuration-i18) - [Configuration Details](#configuration-details) - [tagInclude : Array](#taginclude-array-string) - [tagExclude : Array](#tagexclude-array-string) - [attInclude : Array](#attinclude-array-string) - [attExclude : Array](#attexclude-array-string) - [defaultLanguage: String](#defaultlanguage-string) - [languages: Array](#languages-array-string) - [translationFile: String](#translationfile-string) - [maxIdLength: Int](#maxidlength-int) - [prefix: String](#prefix-string) - [suffix: String](#suffix-string) - [Variables](#variables) - [Replacing Strings](#replacing-strings) - [Selection Method](#selection-method) - [Table Method](#table-method) - [Table Actions](#table-actions) - [Save](#save) - [Ignore](#ignore) - [Mark Translatable](#mark-translatable) - [Save Value](#save-value) - [Update Value](#update-value) - [Remove](#remove) - [Update Value](#update-value-1) - [View Usage](#view-usage) - [View Translation](#view-translation) - [Table String Sources](#table-string-sources) - [Templates](#templates) - [Element Attributes](#element-attributes) - [Element Content](#element-content) - [Scripts](#scripts) - [Plain Old Javascript](#plain-old-javascript) - [Component Options](#component-options) - [Stylesheets](#stylesheets) - [String ID Names](#string-id-names) - [String ID Autocompletion And Insertion](#string-id-autocompletion-) - [Inserting A String Using The Dialog](#inserting-a-string-using-) - [Navigating To A Translation](#navigating-to-a-translati) - [Finding String ID Usages](#finding-string-id-usages) - [Metadata](#metadata) - [Translation File](#translation-file) - [Sample YAML file](#sample-yaml-file) - [Merge Strategy](#merge-strategy) - [Refactoring](#refactoring) - [Common Actions](#common-actions) - [Translate](#translate) - [Translate ID All](#translate-id-all) - [Translate All](#translate-all) - [Clear Translations](#clear-translations) - [Goto Usages](#goto-usages) - [Goto Translation](#goto-translation) - [Language Detection](#language-detection) - [Show All Strings](#show-all-strings) - [Show Untranslated Strings](#show-untranslated-strings) - [Rename Symbol](#rename-symbol) - [Merge Symbols](#merge-symbols) - [Verify Translations](#verify-translations) - [Find Usages Of String ID](#find-usages-of-string-id) - [Other](#other) - [Features](#features) - [TODO](#todo) - [Wish List](#wish-list) - [Issues](#issues) # Overview This tool will take a Vue Single File Component, such as this: ```vue ``` And replace the strings with IDs and a lookup function (using the `vue-i18n` format). ```vue ``` A `.yaml` file will be created with source strings. ```yaml welcome: Welcome to my Vue application appName: My Application ``` The plugin can handle string literals in interpolated elements and attributes, spliting and formatting along the way. ```
Hello {{ 'very very strange' + getWorld() }}
``` Once a string is defined, you can then create other language files and translate your strings manually or automatically. A full suite of refactoring tools is provided. All i18n commands are placed in the main menu bar under the `i18n` item. # Roadmap Our roadmap has paved the way for other implementations besides `Vue` source code and `YAML` data stores. The application currenty only supports *Vue* source code using *YAML files* as a store. ## Source Implementation | Platform | Implemented | |---|---| | Vue | Yes | | React | No | | Angular | No | | HTML | No | | C | No | | C# | No | | Perl | No | | Visual Basic | No | | Objective C | No | ## Data Store Implementation | Platform | Implemented | |---|---| | YAML | Yes | | Property File | No | | MySql | No | # Configuration A file called `i18n.config.js` is used for settings related to translation. This file is an es6 module that exports a default object containing your preferences. The file is located by finding the first directory containing a configuration file, starting from the component's directory, and then moving upwards. If no file is found, default settings are used. You can use multiple configurations in a project by including multiple configuration files in various subdirectories. You can automatically create a default configuration file in your module's root directory using the command `i18n/Create i18n Configuration File`. This file will contain the default settings that would be used if the file did not exist. Invalid configurations files will be ignored, and a warning notification will be displayed. ## Configuration Settings ### Example Configuration (i18n.config.js) ```js // i18n Configuration export default { // String Detection Filtering tagInclude:[], // 'div', 'span', 'p', 'button' tagExclude:[], attInclude:[], // 'title', 'caption', 'label', 'value', 'placeholder' attExclude:[], // Languages defaultLanguage: 'en', languages:['en','sp','fr'], // Translation Data location translationFile: 'i18n/{{language}}.yaml', // String ID Generation maxIdLength: 64, prefix: '', suffix: '', } ``` ### Configuration Details #### tagInclude : Array Tags to include for analysis in the translation table. #### tagExclude : Array Tags to exclude from analysis from the translation table. #### attInclude : Array Attributes to include as suggestions in the translation table. Attributes are allowed in any element, regardless of the `tagInclude` and `tagExclude` settings. Including `foo` will also include the attributes decorated with `:` and `.`, such as `:foo`, `v-bind:foo`, and 'v-bar:foo.abc' #### attExclude : Array Attributes to exclude as suggestions from the translation table. Attributes are ignored in any element, regardless of the `tagInclude` and `tagExclude` settings. #### defaultLanguage: String default: 'en' The default language to use. This is applied when generating the name of the `.i18n..yaml` file to create and sync with. #### languages: Array default: undefined A list of languages to consider. The default language is always included, even if not in this list. If the list is not defined, the default language file's directory is scanned. Default `yaml` files will be created for each language in this array. #### translationFile: String default: `i18n/{{language}}.yaml` The path (relative to the configuration file or Vue component) used to store and retrieve translations. By default, this is in the component's directory with the filename being the name of the component + `.i18n` + the default language + `.yaml`. This will load and save translations in an `i18n` subdirectory next to your configuration file. Your component's filename will replace the {{component}} part of the path. (`{{component}}.i18n.{{language}}.yaml`) Your default language ID will replace the `{{language}}` part of your path. If you specify a component parameter, the path is relative to the component. Otherwise, the path is relative to the configuration file. The result would be a file next to your component with a name like `my-component.vue.i18n.en.yaml`. To store all strings in a common file, do not use the {{component}} parameter. For example, assuming your configuration is at the root of your project and your translations are in the `src/i18n` directory, use the path `src/i18n/{{language}}.yaml` #### maxIdLength: Int default: 64 The maximum length of a generated ID. For example, if `ids.maxLength: 7`, `This is a long string` will become `thisIsA`. If an extension is added to the ID to make it unique, it is added to the restricted length, making the string the maxLength plus the extension's length. #### prefix: String : A prefix added to the start of each newly generated string ID. Variables can be used. Dots can be used for nesting. ```js { prefix: 'generated.', suffix: "_steven" } ``` This configuration would result in the string `Hello World` being named MyPrefix.helloWorld\_MySuffix. In YAML: ```yaml generated helloWorld_steven ``` #### suffix: String : A suffix added to the end of each newly generated string ID. Variables can be used. Dots can be used for nesting. ## Variables Variables can be enclosed in configuration strings using the `{{variable\_name}}`` format. ~ todo document the following variables ~ - language - component - component\_filenameß - component\_name # Replacing Strings There are 2 methods used to replace literal strings, *Selection* and *Table*. ## Selection Method With the *Selection Method*, the user selects text in a file and then executes the *translate selected* command from the *Translate* tab, the *Analyze* menu. or using a keyboard shortcut. An ID will be suggested in a prompt dialog. If the user continues the following items will be performed. 1. The text will be replaced with a lookup method using a string ID. 2. Surrounding text will be modified if needed to merge the lookup with it's surroundings. 3. Attribute nodes will change to an interpolated v-bind attribute (from foo to :foo) if not already set to one. 4. `.18n.json` and `.18n.yaml` files will be created and/or updated. 5. The translation table in the *Translate* tab will refresh. This method can be used to selected strings that are excluded from the table analysis, or are not detected correctly. > This command is only enabled when a `.vue` file is active. > > The keyboard shortcut for this command is `shift-control-alt-t`. ## Table Method The user views translations in a table. 1. List the strings used in templates and script blocks 2. Mark each string as either *translate* or *ignore* 3. Adjust the text and id for new string entries 4. Add all string settings to a metadata file. 5. Sync the metadata file with a `*.yaml` file. All string literals inside `t$()` methods are assumed to be string IDs. They may or may not have been tranlated or mapped. ### Table Actions Each table section has various actions that can be preformed on items. #### Save Save new id-value pairs, or create a value for an upmapped id. Your new items will be added to the metadata and the items will be merged into the translation file. A fields at the top of the table allows you to set a common dot-prefix for all saved strings. For example: You set the prefix to `foo.bar` and create a string ID `manchu`. The string ID will be saved as `foo.bar.manchu`. #### Ignore Mark a string as excluded. #### Mark Translatable Unmark an excluded string. #### Save Value You can enter string IDs into your Vue template, and then define the string value later. The table report has a section listing *String IDs that are referenced in the component but have no translation.*This section allows you to specify the text in your default language. When you save the value, it will be added to your metadata and translation file. #### Update Value You can replace the string value of an ID directly in the the table by updating the text field and pressing the *Update Value* button. #### Remove Remove the string ID and value from the metadata and the YAML file. Once you map a value, it stays in the metadata until you remove it. You can manualy remove the metadat entry by pressing the *Remove* button. This will **not** remove the string from the translation table. #### Update Value Change the value for a string ID #### View Usage Open and select the template reference for the string entry. #### View Translation Open and select the YAML translation for the string entry. ### Table String Sources A `string source` refers to *where a string literal is located*. For template blocks, this includes attributes, interpolated attributes, elements, and interpolated elements, For script blocks, this includes literals in both component options (such as `data` and `computed`) and global Javascript declared outside the component. #### Templates ##### Element Attributes For attributes, that means `:foo=` and `v-bind:foo` must be inside quotes, `foo=` is considered to be translatable. ##### Element Content For element content, the strings must appear outside handlebars (`{{ }}`), or inside handlebars with quotes (`'`, `"`, or `backquote`). #### Scripts ##### Plain Old Javascript ##### Component Options #### Stylesheets todo: # String ID Names String IDs that contain dots will be nested in the `.yaml` file. So `foo.man.chu` will become ```yaml foo: man: chu: ``` # String ID Autocompletion And Insertion The i18n plugin can offer suggestions for inserting string IDs, and insert the lookup function into your source code. ## Inserting A String Using The Dialog Start by opening a file and placing the cursor where you want to insert the string lookup function. If you select a range, the range will be replaced. Open the *Insert String* dialog using the `i18n/Insert String` command, or an assigned keyboard shortcut. Select a string in the list and press `Enter` or the `OK` button. > > > You can type characters and use up-down arrows to filter the list. If you are entering a string inside a `Vue style` section, the lookup function will be prepended with `this.`. `Vue template` sections will leave the `this.` prefix out. # Navigating To A Translation You can navigate to a `YAML` translation file by placing the caret on a string ID in your source code, and then selecting the `i18n/Goto Translation` menu item. The `YAML` file will open and the caret will move to the translation. # Finding String ID Usages You can navigate to string ID usages by placing the caret on a string ID in your source code or a YAML file, and then selecting the `i18n/Goto Usages` menu item. The source files will open and the caret will move to the usage. # Metadata Metadata for a component is stored in a `JSON` file using the name of the component + `.i18n.json`. So `foo.vue` will have a companion file called `foo.vue.i18n.json`. This file helps define what is translated, and what is ignored. # Translation File The metadata is converted into a translation file called `foo.vue.i18n.en.yaml`. The filename prefix is the filename of the component. The language part of the file name is taken from the configuration settings. The format is a standard `yaml` file with keys being the string ID and values being the translated value for the specifed language. ## Sample YAML file ```yaml hello: Hello world: World thisIsATest: This is a test ``` ### Merge Strategy When you save your string table, new entries are added, existing entries are updated, and YAML values not mapped are left unchanged. # Refactoring Refactoring uses a filterable table to present items and actions. In most case, you can edit-in-place without needing to explicitly save. ## Common Actions ### Translate Translate a string into the selected language. ### Translate ID All Translate all untranslated strings for a given ID. ### Translate All Translate all untranslated strings for strings in all languages. ### Clear Translations Resets all translations for every language, except for the default language. This can be done per stringID, single source file, or all source files. ### Goto Usages Open and navigate to all usages of a string ID. ### Goto Translation Open the translation file for a string ID for the specified language. ## Language Detection Languages are detected by finding `yaml` files in your translation directory. If your configuration is `i18n/{{language}}.yaml`, then all `yaml` files in the `i18n` directory will be scanned to determine your active languages. ``` i18n.config.js i18n/ en.yaml es.yaml fr.yaml ``` 3 languages (English, Spanish, and French) will be detected. ## Show All Strings - List all strings IDs along with each translation for every language. - Goto component usages - Goto translation yaml file. - Edit in-place - Auto Translate using Google Translate - Add a prefix to ID automatically ## Show Untranslated Strings Same as *Show All Strings*, but only shows item that have not been translated. The default language is alsow shown ## Rename Symbol You can rename a string ID in all yaml files and referencing files. ## Merge Symbols You can merge a string ID with another string ID by *Renaming* it to an existing ID. The renamed version will overwrite the existing value. ## Verify Translations todo: implement ## Find Usages Of String ID Show all usages of a string ID in source code. ## Other - Remove Symbol And Replace With Text - Language Reports - Online Portal For Editing - Add or remove component prefix in string ID # Features - Full undo support. - Jump to any usage or translattion directly from the string editor. - Mark strings as exclude. - Configure tags and attributes to consider or exclude. - Set ID and modify text from the string editor. - Generate custom string IDs - Merge with existing `.yaml` files. - Change existing strings directly from table - Goto source symbol, source text, or translation from table item # TODO - Only store exclusions in metadata, and do not create metadata at all if no exclusions exist. - Reuse existing string if conflict in name. - Special characters are not escaped in translations. - Add moustache around inserted lookup methods. # Wish List - Auto clean metadata - Add string insertion - HTML values attribute insertion - Stylesheet support. # Issues Send bugs and feature requests to [ ](https://www.twelvetone.tv/docs/developer-tools/intellij-plugins/maven-gradle-navigation) [](https://www.twelvetone.tv/docs/developer-tools/intellij-plugins/intellivue) --- ## Navigation - Parent: [IntelliJ Plugins](https://www.twelvetone.tv/docs/developer-tools/intellij-plugins.md) - Previous: [Maven/Gradle Navigation](https://www.twelvetone.tv/docs/developer-tools/intellij-plugins/maven-gradle-navigation.md) - Next: [IntelliVue](https://www.twelvetone.tv/docs/developer-tools/intellij-plugins/intellivue.md)