diff --git a/topics/appendix/api_notable/api_notable_list_2024.md b/topics/appendix/api_notable/api_notable_list_2024.md
index f2fe8b573..433d2c1a5 100644
--- a/topics/appendix/api_notable/api_notable_list_2024.md
+++ b/topics/appendix/api_notable/api_notable_list_2024.md
@@ -17,6 +17,9 @@ _Early Access Program_ (EAP) releases of upcoming versions are available [here](
### IntelliJ Platform 2024.1
+Bundled Localization
+: Initial plugin [localization](providing_translations.md#translated-elements) capabilities.
+
Using Coroutines
: It is now recommended to use [](kotlin_coroutines.md) for asynchronous code.
diff --git a/topics/intro/content_updates.md b/topics/intro/content_updates.md
index a13d8ec59..df97acbab 100644
--- a/topics/intro/content_updates.md
+++ b/topics/intro/content_updates.md
@@ -15,6 +15,9 @@ See [GitHub Changelog](https://github.com/JetBrains/intellij-sdk-docs/commits/ma
### April
{april-24}
+Plugin Internationalization
+: Add [](internationalization.md) and [](providing_translations.md) pages describing IDE and plugin translation possibilities and best practices.
+
Minor Changes and Additions
:
- How to mark functionality available during indexing via [](indexing_and_psi_stubs.md#DumbAwareAPI).
diff --git a/topics/reference_guide/localization/internationalization.md b/topics/reference_guide/localization/internationalization.md
new file mode 100644
index 000000000..f4f429020
--- /dev/null
+++ b/topics/reference_guide/localization/internationalization.md
@@ -0,0 +1,377 @@
+
+
+# Internationalization
+
+Tips about implementing message bundles, organizing translations, etc.
+
+To enable IntelliJ-based IDEs and plugins for _National Language Support (NLS)_, all `String` instances in the code can be split into three categories:
+- **NLS strings** - strings which are shown to users in the UI: texts in dialogs, menu items, descriptions of inspections, error messages, etc.
+- **non-NLS strings** - strings which are used internally and aren't shown in UI: attributes in configuration files, keys in indices and caches, etc.
+- **NLS-safe strings** - strings which don't need to be localized but can be shown in UI: strings written by users (e.g., parts of program code, file names, URLs, etc.), names of frameworks (in some cases names of frameworks may be translated, e.g., if they consist of multiple words), etc.
+
+By default, a string is considered as non-NLS.
+
+## NLS Annotations
+
+There is a set of NLS-related annotations, which can be used for annotating strings in the IDE or plugin code.
+Annotating strings enables inspecting NLS string content correctness.
+
+For example, if an API method parameter is annotated as an NLS string, any hardcoded string passed as a value will be reported and extracting it to a message bundle will be proposed as a quick fix.
+Another example is inspecting whether a given string value is properly capitalized for the usage context.
+
+> Internationalization-related inspections can be enabled in Settings | Editor | Inspections in the following groups (some inspections require enabling _Java Internationalization_ bundled plugin):
+> - Java | Internationalization
+> - Java | Properties files
+> - Properties files
+
+Consider using the following annotations:
+- [`@Nls`](%gh-java-annotations%common/src/main/java/org/jetbrains/annotations/Nls.java) - for NLS strings.
+ The `capitalization` attribute allows to specify required capitalization.
+- [`@NonNls`](%gh-java-annotations%common/src/main/java/org/jetbrains/annotations/Nls.java) - for non-NLS strings
+- [`@NlsSafe`](%gh-ic%/platform/util/base/src/com/intellij/openapi/util/NlsSafe.java) - for NLS-safe strings
+
+### NLS Context Annotations
+
+NLS context annotations are semantic annotations describing the context where the annotated strings are intended to be used.
+For example, [`@InspectionMessage`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInspection/util/InspectionMessage.java) should be used for strings displayed as messages reported by inspections.
+
+NLS context annotations must be annotated with `@Nls` and they can define:
+- capitalization requirement - via `@Nls.capitalization` attribute
+- [`@NlsContext`](%gh-ic%/platform/util/src/com/intellij/openapi/util/NlsContext.java) - specifies default prefix and suffix for property keys, which will be suggested by the I18nize hardcoded string literal quick fix provided by Java | Internationalization | Hardcoded strings inspection
+
+The IntelliJ Platform provides NLS context annotations, including:
+- general contexts: [`NlsContexts`](%gh-ic%/platform/util/src/com/intellij/openapi/util/NlsContexts.java) nested annotations
+- action contexts: [`NlsActions`](%gh-ic%/platform/editor-ui-api/src/com/intellij/openapi/util/NlsActions.java) nested annotations
+- miscellaneous contexts: [`@InspectionMessage`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInspection/util/InspectionMessage.java), [`@IntentionFamilyName`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInspection/util/IntentionFamilyName.java), [`@IntentionName`](%gh-ic%/platform/analysis-api/src/com/intellij/codeInspection/util/IntentionName.java), [`@GutterName`](%gh-ic%/platform/lang-api/src/com/intellij/codeInsight/daemon/GutterName.java), [`@TooltipTitle`](%gh-ic%/platform/platform-api/src/com/intellij/ide/TooltipTitle.java)
+
+To find all available annotations, search for `@NlsContext` usages in the [intellij-community](https://github.com/JetBrains/intellij-community) source code.
+
+If the provided set of NLS context annotations are not sufficient, create custom annotations.
+
+### A Single NLS Category Restriction
+
+It is important not to use the same string instance for both NLS and non-NLS categories.
+If it is required to use some class as a key in configuration files and present it in the UI, create two separate methods (`getId`, `getDisplayName`) even if they return the same value in the default locale.
+
+### Avoiding Non-NLS Strings in Message Bundle
+
+To enable localization, all NLS strings must be placed in [resource bundle](#message-bundles) files.
+It is important to avoid adding non-NLS strings to a resource bundle.
+At best, this will add unnecessary work for translators, but it is also quite possible that if such a string is translated, it could break some features.
+
+## Message Bundles
+
+All NLS strings from a module should be added to a *.properties file.
+A standard location of message files in JAR is /messages/\*.properties.
+In [Gradle-based plugin](developing_plugins.md#gradle-intellij-plugin) project sources, message files are located in $MODULE_ROOT$/src/main/resources/messages/\*.properties.
+
+> A standard convention for naming message bundle properties file is *Bundle.properties.
+
+A corresponding [bundle class](#message-bundle-class) should be used to access the strings from the code.
+
+### Message Bundle Class
+
+The recommended approach to create a bundle class is to delegate getting messages to [`DynamicBundle`](%gh-ic%/platform/core-api/src/com/intellij/DynamicBundle.java), e.g.:
+
+
+
+
+
+```kotlin
+@NonNls
+private const val BUNDLE = "messages.ExampleBundle"
+
+internal object ExampleBundle {
+ private val INSTANCE = DynamicBundle(ExampleBundle::class.java, BUNDLE)
+
+ fun message(
+ key: @PropertyKey(resourceBundle = BUNDLE) String,
+ vararg params: Any
+ ): @Nls String {
+ return INSTANCE.getMessage(key, *params)
+ }
+
+ fun lazyMessage(
+ @PropertyKey(resourceBundle = BUNDLE) key: String,
+ vararg params: Any
+ ): Supplier<@Nls String> {
+ return INSTANCE.getLazyMessage(key, *params)
+ }
+}
+```
+
+
+
+```java
+final class ExampleBundle {
+ @NonNls
+ private static final String BUNDLE = "messages.ExampleBundle";
+ private static final DynamicBundle INSTANCE =
+ new DynamicBundle(ExampleBundle.class, BUNDLE);
+
+ private ExampleBundle() {}
+
+ public static @NotNull @Nls String message(
+ @NotNull @PropertyKey(resourceBundle = BUNDLE) String key,
+ Object @NotNull ... params
+ ) {
+ return INSTANCE.getMessage(key, params);
+ }
+
+ public static Supplier<@Nls String> lazyMessage(
+ @NotNull @PropertyKey(resourceBundle = BUNDLE) String key,
+ Object @NotNull ... params
+ ) {
+ return INSTANCE.getLazyMessage(key, params);
+ }
+}
+```
+
+
+
+
+Do not extend `DynamicBundle` in bundle classes.
+
+Annotating message key parameter with [`@PropertyKey`](%gh-java-annotations%common/src/main/java/org/jetbrains/annotations/PropertyKey.java) adds the IDE support in the client code, e.g., reporting unresolved message keys.
+
+### Moving Strings to Message Bundles
+
+IntelliJ IDEA provides inspections with fixes which help with moving strings to message bundles, e.g. Editor | Inspections | Java | Internationalization | Hardcoded strings for Java and Kotlin code.
+
+It is possible to move multiple hardcoded strings to a message bundle in batch mode.
+
+
+
+1. Invoke the Code | Analyse Code | Run Inspection by Name... action.
+2. Select the Hardcoded strings inspection.
+3. Select the inspection scope and run the inspection.
+4. In the Problems tool window, select the items to internationalize.
+5. Invoke the I18nize hardcoded string literal quick fix.
+6. Provide the message bundle file and resource bundle expression.
+7. Review the internationalized messages. It is possible to delete items and adjust their keys.
+8. Click the OK button.
+
+
+
+## Internationalization Tips
+
+### Property Keys
+
+It is important to specify a prefix for the property key describing the context in which UI string is used, especially for short strings.
+
+For example, `set=Set` property is hard to translate as the message usage context is unclear.
+It is required to find usages of such a message to properly translate it, which is a very time-consuming process.
+Also, other developers may reuse the same property for a different meaning of the word, and after that it will be impossible to translate it correctly.
+
+The simplest way to specify the prefix is annotating the parameter with one of [`@NlsContext` annotations](#nls-context-annotations).
+It will cause the IDE to generate prefix and suffix automatically when the string is moved to a message bundle.
+
+### Using `&` in Messages
+
+The `&` symbol in message bundles is used to specify [mnemonic](https://jetbrains.design/intellij/principles/mnemonics/) characters for buttons and labels.
+To use `&` in a value, escape it by a backslash (note that you also need to escape the backslash symbol):
+```
+section.title=Drag \\\& Drop
+```
+
+### Long Values
+
+To wrap a long value in a message bundle, put a backslash at the end of the line, and continue the value on the next line with an indent.
+Starting spaces on the next line are ignored, so if a space character is required before the word in the next line, add a space before the backslash:
+```
+key=very, very long \
+ description
+```
+
+In the above example, `message("key")` evaluates to `very, very long description`.
+
+Note that the backslash at the end of a line doesn't add a line break into the resulting value.
+For line breaks, use `\n`.
+
+### Avoid Programmatic String Transformations
+
+They include but are not limited to:
+- capitalization (e.g., "usage" and "Usage")
+- pluralization (e.g., "child" and "children")
+- grammatical casing ("das Projekt" and "dem Projekt" - "the project" in German used for different grammatical cases: "the project" and "of the project" accordingly)
+- gender-based modification (e.g., "nuevo" and "nueva" - "new" in Spanish used for a masculine and feminine subject accordingly)
+
+Such transformations make the incorrect assumption about:
+- existence of a transformation in another language (e.g., there might be no casing in some language)
+- rules of transformation in another language (e.g., capitalization rules may differ)
+- context of the transformed string (e.g., the same word might be used in different contexts)
+
+In all above cases, it is better to put the result string into the bundle.
+Example:
+
+
+
+ |
+ Wrong
+ |
+
+ Correct
+ |
+
+
+ |
+ Message bundle:
+
+ term.node=node
+
+
+ Code:
+
+ message("term.node")
+ pluralize(message("term.node"))
+
+ |
+
+ Message bundle:
+
+ term.node=node
+ term.nodes=nodes
+
+ Code:
+
+ message("term.node")
+ message("term.nodes")
+
+ |
+
+
+
+### Internationalization of String Concatenations
+
+#### Concatenation of Localized Strings and User Input
+
+If an NLS string is not a simple literal but obtained as a concatenation of several values, always use [MessageFormat](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/MessageFormat.html) pattern to extract it to a message bundle.
+
+For example, to internationalize `"Delete Class " + className` add the following property:
+```
+title.delete.class=Delete Class {0}
+```
+and access it with `message("title.delete.class", className)` in the client code.
+
+Patterns should be used even if the changing part of the string is the last or the first element in the concatenation, because this may change when the message is translated to a language with a different grammar.
+
+> Note that single quotes are used for escaping in `MessageFormat` patterns, and to use `'` character it is required to double it: `''`.
+>
+> For example, below are the correct sentences:
+> ```
+> # single quote in the value below is not escaped,
+> # because MessageFormat pattern is not used:
+> checkbox.text.do.not.show.again=Don't show again
+>
+> # single quote in the value below is escaped,
+> # because MessageFormat pattern is used (notice "{0}"):
+> error.message.file.does.not.exist=File {0} doesn''t exist
+> ```
+>
+{title="Escaping Single Quotes in MessageFormat Patterns"}
+
+#### Avoid Composing NLS Strings from Parts
+
+If it is required to include a dynamically obtained string in a message, it is necessary to use message patterns as described above.
+However, in other cases, it is better to avoid composing NLS strings from smaller parts stored in separate properties:
+- the concatenation of words in the sentence incorrectly assumes that the translated sentence will have the same words in the same order and form in other languages
+- it is harder to properly translate messages
+
+The following example won't be translated correctly into the languages which use word cases:
+
+English messages:
+```
+dialog.title.add.0=Add {0}
+dialog.title.edit.0=Edit {0}
+dialog.title.name.0.1={0} ''{1}''
+concept.library=Library
+concept.dependency=Dependency
+```
+
+Polish translations:
+```
+dialog.title.add.0=Dodaj {0}
+dialog.title.add.0=Edytuj {0}
+concept.library=Bibilioteka
+concept.dependency=Zależność
+```
+
+Correct result:
+```kotlin
+message("dialog.title.name.0.1", message("concept.library"), "foo")
+// Biblioteka 'foo'
+```
+
+Wrong result:
+```kotlin
+message("dialog.title.add.0", message("concept.library"))
+// Dodaj Biblioteka
+// wrong case and capitalization (correct: "Dodaj bibliotekę")
+```
+
+If several localized strings (non-user input) are used to concatenate the string, then the following techniques can be used (in order of preference):
+1. Consider reworking the UI to avoid the string concatenation (consult the UX expert if your organization has any, or check [IntelliJ Platform UI Guidelines](https://jetbrains.design/intellij/)).
+ - Put string parts into different UI elements.
+ - Remove a UI element which shows the concatenated string.
+2. Rephrase the string.
+ - Use a generic term:
+ `"Select " + term + " to preview"` where term is `"usage"` or `"occurrence"` or `"match"` → `"Select result to preview"`.
+ - Don't use the term at all:
+ `"Preview " + term` → `"Preview"`
+
+ The UI might still need a slight rework to be clear what will be previewed (consult the UX expert if possible).
+ - In some cases, it might be correct to use the sentence concatenation:
+ ```
+ guidelines.browser.tab.name={0} | IntelliJ Platform UI Guidelines
+ google.docs.browser.tab.name={0} - Google Docs
+ ```
+3. Provide the whole string for each context and term pair:
+ ```
+ dialog.title.add.library=Add Library
+ dialog.title.edit.library=Edit Library
+ dialog.title.name.library.0=Library ''{0}''
+ dialog.title.add.dependency=Add Dependency
+ dialog.title.edit.dependency=Edit Dependency
+ dialog.title.name.dependency.0=Dependency ''{0}''
+ ```
+ This approach is the least preferred:
+ - Given X terms and Y contexts, it will result in X*Y strings.
+ It is acceptable to have several strings for small X and Y.
+ For more cases, the translations may become unmaintainable.
+ - If terms are provided other by plugins via an extension point, the extension point API would require a change to provide full strings.
+
+#### Messages Depending on Numbers
+
+Sometimes it is required to change a message depending on a number, for example, to pluralize a noun or use a proper form for a verb.
+In that case, use ChoiceFormat patterns.
+
+It starts with an index of the argument which will be used for choosing a variant, then the `choice` word follows,
+and the rest specifies pairs of numbers and corresponding values separated by `|`.
+
+For example, for pattern:
+```
+title.selected.files=Selected {0,choice,1#File|2#Files}
+```
+the expression `message("title.selected.files", count)` will evaluate to:
+- `"Selected File"` if `count` is `1` or less
+- `"Selected Files"` if `count` is `2` or greater
+
+The number before `#` characters does not specify the exact value but start of the range.
+The corresponding variant will be used if the argument is greater or equal to the number in this clause and less than the number in the next clause.
+For example, for pattern:
+```
+label.selected.files={0,choice,0#No files are|1#One file is|2#A few files are|10#Many files are} selected
+```
+the expression `message("label.selected.files", 6)` will evaluate to `"A few files are selected"`.
+
+If an argument is referred in one of the choice's variants, it becomes a message pattern itself, and this **adds additional layer of escaping of single quotes**, so to add `'` character in such a variant, add: `''''`.
+For example, below is the correct sentence:
+```
+warning.message={0,choice,1#One person doesn''t|2#{0} people don''''t} like MessageFormat
+```
+
+In some cases, the ordinal format can be useful.
+It adds an appropriate ending to numbers, so it turns into `1st`, `2nd`, `3rd`, `10th`, and so on:
+```
+parameter.cast.fix=Cast {0,number,ordinal} parameter to {1}
+```
diff --git a/topics/reference_guide/localization/providing_translations.md b/topics/reference_guide/localization/providing_translations.md
new file mode 100644
index 000000000..3986fe57d
--- /dev/null
+++ b/topics/reference_guide/localization/providing_translations.md
@@ -0,0 +1,131 @@
+
+
+# Providing Translations
+
+Translating IDE and plugin texts used in UI, inspections, file templates, etc.
+
+Translations for IntelliJ Platform products and plugins can be provided in two ways:
+- [](#language-packs)
+- [](#bundled-translations)
+
+## Language Packs
+
+Localizing IDEs is achieved by providing language packs (see available [language packs](https://plugins.jetbrains.com/search?tags=Language%20Pack)).
+Language packs are IntelliJ Platform plugins containing translations of UI texts.
+Official language packs contain translations of all the UI texts used in the IDE and in plugins developed by JetBrains.
+
+Please note that language packs aim for full IDE localization.
+If it is required to translate a plugin, see the [](#bundled-translations) section.
+
+Language packs must define their language.
+The language definition is provided in the [`plugin.xml`](plugin_configuration_file.md) file with `com.intellij.languageBundle` extension point (EP), e.g.:
+```xml
+
+
+
+```
+
+The `locale` attribute defines the translation language on two possible levels:
+- region level, e.g.: `zh-CN` - Chinese (Simplified), `zh-TW` - Chinese (Taiwan)
+- language level, e.g., `ja` - Japanese
+
+> Please note that `com.intellij.languageBundle` EP is internal and should be used by JetBrains only.
+>
+{style="warning"}
+
+### Language Selection
+
+It is important to note that there is no language chooser available in the IDE and language packs serve as the IDE "language switcher".
+Installing a language pack changes the IDE language to the one defined by the `languageBundle` EP.
+Only a single language pack can be installed at the same time, and restart is required for the translations to take effect.
+
+### Language Pack Translations Structure
+
+See the [translated elements](#translated-elements) list for the elements possible to translate.
+All the elements should be located in exactly the same paths as in original locations in their JAR files.
+
+For example, if the original location of a message bundle is $PLUGIN_JAR$/messages/AbcBundle.properties, it must be located in $LANGUAGE_PACK_JAR$/messages/AbcBundle.properties.
+
+It is allowed to organize them within [localization directories or with file name language suffixes](#bundled-translations-structure), but it is unnecessary as language pack can define only a single language.
+
+In case of doubts, it is recommended to inspect the contents of existing language packs.
+
+## Bundled Translations
+
+Since 2024.1, IntelliJ Platform partially supports providing translations directly bundled in the IDE or plugins.
+See the [translated elements](#translated-elements) list for the elements possible to translate.
+
+An IDE module or a plugin can provide multiple language translations in a single distribution, e.g., `zh-CN` and `ja`.
+Proper localization files will be used at runtime depending on the [IDE language](#language-selection).
+
+### Bundled Translations Structure
+
+Translations for a specific language can be organized in two ways:
+- Language directory: /localization/$LANGUAGE_CODE$/$REGION_CODE$ (`$REGION_CODE$` level is optional).
+ Example:
+ - Original template description:
+
+ /fileTemplates/code/JavaDoc Class.java.html
+ - Translated template description:
+
+ /localization/zh/CN/fileTemplates/code/JavaDoc Class.java.html
+- Localization suffix in file name: /intentionDescriptions/QuickEditAction/description_$LANGUAGE_CODE$_$REGION_CODE$.html.
+ Example:
+ - Original template description:
+
+ /intentionDescriptions/QuickEditAction/description.html
+ - Translated template description:
+
+ /intentionDescriptions/QuickEditAction/description_zh_CN.html
+
+The proper directory layout/file name suffixes is the only thing needed for the translations to work.
+No additional actions like registering EPs are needed.
+
+## Translated Elements
+
+The following table contains the possible translated elements and information about their support in language packs and IDE/plugins.
+
+| Element | Language Pack | Bundled Translations |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|----------------------|
+| [Message bundles](internationalization.md#message-bundles)(*.properties files)
| Yes | Since 2024.1 |
+| [Inspection descriptions](code_inspections.md#inspection-description)(*.html files in /inspectionDescriptions directory)
| Yes | Since 2024.1 |
+| [Intention descriptions](code_intentions.md#about-intention-actions)(*.html files in /intentionDescriptions directory)
| Yes | Since 2024.1 |
+| [Searchable options](tools_intellij_platform_gradle_plugin_tasks.md#buildSearchableOptions)(*.xml file in /search)
| Yes | 2024.2 (planned) |
+| [File template descriptions](providing_file_templates.md#creating-file-template-description)(*.html files in the /fileTemplates directory)
| Yes | 2024.2 (planned) |
+| [Postfix template descriptions](postfix_templates.md#postfix-template-description)(*.xml file in /postfixTemplates directory)
| Yes | 2024.2 (planned) |
+| Tips of the day*.html files in tips directory
| Yes | 2024.2 (planned) |
+
+See the [IntelliJ Platform UI Guidelines | Text](https://jetbrains.design/intellij/text/capitalization/) sections for good practices about writing UI texts.
+
+## Translation Priority
+
+Translations can be provided on three different levels:
+- region-specific translation
+- language-specific translation
+- default translation (English)
+
+In addition, translations can be [organized in directories or with file suffixes](#bundled-translations-structure), and the same translation can be provided by a [language pack](#language-packs) or [IDE/plugin](#bundled-translations).
+
+All these conditions determine how a single translation is resolved at runtime.
+The priority is as follows:
+1. Region level (e.g., `zh_CN`, `zh_TW`) localization file:
+ 1. located within the localization directory of the language pack
+ 2. located within the localization directory of the IDE or plugin
+ 3. via suffix within the language pack
+ 4. via suffix within the IDE or plugin
+
+ {type="alpha-lower"}
+2. Language level (e.g., `zh`) localization file:
+ 1. located within the localization directory of the language pack
+ 2. located within the localization directory of the IDE or plugin
+ 3. via suffix within the language pack
+ 4. via suffix within the IDE or plugin
+
+ {type="alpha-lower"}
+3. Default file (no suffix) within:
+ 1. the language pack
+ 2. the IDE or plugin
+
+ {type="alpha-lower"}
+
+
diff --git a/topics/reference_guide/localization_guide.md b/topics/reference_guide/localization_guide.md
deleted file mode 100644
index ddd347162..000000000
--- a/topics/reference_guide/localization_guide.md
+++ /dev/null
@@ -1,59 +0,0 @@
-
-
-# Localization Guide
-
-Providing translations for IDE texts used in UI, inspections, file templates, etc.
-
-The purpose of the document is to describe steps necessary to create localized versions of IDEA.
-
-## Application Bundle Layout
-
-In regard to localization purpose all the resources (in English) that need to be translated are located in JAR files called
-resources_en.jar.
-There's one such JAR file for IDEA core functionality located at
-INSTALL_HOME/lib/resources_en.jar
-and one JAR for each of bundled plugins at
-INSTALL_HOME/plugins/$Plugin$/lib/resources_en.jar.
-
-Translated resources should be packed to JAR and placed exactly in the same folder original JAR comes from.
-So localization pack should have exactly the same number of JAR files, and they have to be laid out in exactly the same way original JAR files are laid out.
-In order to enable multiple localizations per installation without localization packs overriding each other we suggest to include the name of the locale in the JAR name (for example, resources_ja.jar).
-
-## Content and Layout of resources_en.jar
-
-Property files usually contain messages, menu items, dialog labels texts etc.
-For every such file localized JAR should contain translated version that is placed to exactly the same path relative to the JAR root and has exactly the same name as original file plus locale identifier.
-For example messages/ActionsBundle.properties file from resources_en.jar should have its translated version messages/ActionsBundle_ja.properties file in resources_ja.jar.
-All property files should be ASCII encoded with `\uXXXX` sequences used for characters that have no representation in ASCII range.
-See [native2ascii](https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/native2ascii.html) tool for more details.
-
-Property values mostly follow MessageFormat rules.
-
-> Due to historic reasons main menu, toolbar, popup menus and other actions have their mnemonic char prefixed with `_` (underscore) char while all other mnemonics like those for checkboxes, buttons etc. use `&` (ampersand) sign for the same purpose.
-> Moreover one can encounter `&&` (double ampersand) in some places, which denote alternative mnemonic to be used under macOS (mnemonics mapped to `U`, `I`, `O`, `N` chars won't work there).
-> Generally, use the same mnemonic denotation used in the original property value and everything will be OK.
->
-{style="note"}
-
-## Components Location
-
-* **Inspection descriptions** appear in Settings | Editor | Inspections and represent short information about what each of the inspection tools is intended to do.
- Each description is represented by single HTML file under /inspectionDescriptions/ folder that should be encoded in UTF-8 encoding.
- Localized versions should be stored in folder suffixed with locale instead.
- For instance /inspectionDescriptions/CanBeFinal.html from resources_en.jar translation should be placed in /inspectionDescriptions_ja/CanBeFinal.html in resources_ja.jar.
-* **Intention descriptions and samples** are very similar to inspection descriptions but the layout is a bit more advanced.
- Every intention has a bunch of files located in the folder named after intention's short name in /intentionDescriptions/.
- These files include description.html, which holds description similar to inspection one plus a couple of template files demonstrating what the intention will do on a sample.
- Those templates are optional to translate.
- Similar to inspection descriptions whole intentionDescriptions folder should be suffixed with locale identifier.
- For instance /intentionDescriptions/AddOnDemandStaticImportAction/description.html translation should be placed in /intentionDescriptions_ja/AddOnDemandStaticImportAction/description.html.
- All the HTML files should be UTF-8 encoded.
-* **Tips of the day** follow the same pattern inspections and intentions do.
- For instance translation of /tips/AdaptiveWelcome.html goes to /tips_ja/AdaptiveWelcome.html.
- The only thing special about tips is they use special pattern for denoting shortcuts like *EnterAction*; will be replaced to keystroke mapped to *EnterAction* in currently used keymap at run-time.
- So please make sure you leave such sequences intact while translating.
- Remember UTF-8 encoding.
-* **File templates** again go the same way (if at all should be translated).
- /fileTemplates/Singleton.java.ft goes to /fileTemplates_ja/Singleton.java.ft.
-
-Following Sun rules for property bundles whenever certain resource cannot be found in localized version its default version from resources_en.jar will be used instead.
diff --git a/topics/reference_guide/settings_guide.md b/topics/reference_guide/settings_guide.md
index fb4afd763..b49898cb4 100644
--- a/topics/reference_guide/settings_guide.md
+++ b/topics/reference_guide/settings_guide.md
@@ -90,7 +90,7 @@ The attributes supported by `com.intellij.applicationConfigurable` EP and `com.i
| `provider` | **yes** [(1)](#attribute-notes) | FQN of implementation. See [](#the-configurableprovider-class) for more information. | `ConfigurableProvider` |
| `nonDefaultProject` | **yes** | Applicable _only_ to the `com.intellij.projectConfigurable` (project Settings) EP.
`true` = show Settings for all projects _except_ the [default project](https://www.jetbrains.com/help/idea/configure-project-settings.html#new-default-settings).
`false` = show Settings for all projects.
| `Configurable` |
| `displayName` | **yes** [(2)](#attribute-notes) | The non-localized Settings name visible to users, which is needed for the Settings dialog left-side menu.
For a _localized_ visible name omit `displayName` and use the `key` and `bundle` attributes.
| `Configurable`
`ConfigurableProvider`
|
-| `key` and `bundle` | **yes** [(2)](#attribute-notes) | The [localization](localization_guide.md) key and bundle for the Settings name visible to users.
For non-localized visible names omit `key` and `bundle` and use `displayName`.
| `Configurable`
`ConfigurableProvider`
|
+| `key` and `bundle` | **yes** [(2)](#attribute-notes) | The [localization](internationalization.md#message-bundles) key and bundle for the Settings name visible to users.
For non-localized visible names omit `key` and `bundle` and use `displayName`.
| `Configurable`
`ConfigurableProvider`
|
| `id` | **yes** | The unique, FQN identifier for this implementation.
The FQN should be based on the plugin `id` to ensure uniqueness.
| `Configurable`
`ConfigurableProvider`
|
| `parentId` | **yes** | This attribute is used to create a hierarchy of Settings. This component is declared one of the specified `parentId` component's children. Typically used for placing a Settings panel within the Settings Dialog menu. Acceptable values for `parentId` are given in [](#values-for-parent-id-attribute).
`groupId` is deprecated. [(3)](#attribute-notes)
| `Configurable`
`ConfigurableProvider`
|
| `groupWeight` | no | Specifies the weight (stacking order) of this component within the group of a parent configurable component. The default weight is 0, meaning lowest in the order.
If one child in a group or a parent component has non-zero weight, all children will be sorted descending by their weight. If the weights are equal, the components will be sorted ascending by their display name.
| `Configurable`
`ConfigurableProvider`
|
diff --git a/topics/user_interface_components/ui_faq.md b/topics/user_interface_components/ui_faq.md
index 9fc269c10..fa33bdb70 100644
--- a/topics/user_interface_components/ui_faq.md
+++ b/topics/user_interface_components/ui_faq.md
@@ -1,4 +1,4 @@
-
+
# User Interface FAQ
@@ -42,6 +42,8 @@ Use [`NaturalComparator`](%gh-ic%/platform/util/base/src/com/intellij/openapi/ut
- `shortenTextWithEllipsis()` and `shortenPathWithEllipsis()` to produce abbreviated UI texts ending with '…'
- `quote()` and `unquoteString()` to wrap values: _Usages of "$value$": 218 found_
+See [](internationalization.md) for information about internationalizing plugins.
+
See [`NlsMessages`](%gh-ic%/platform/ide-core-impl/src/com/intellij/ide/nls/NlsMessages.java) to produce localized messages.
## "Recently Used" entries