Internationalization - Revision history

ChampionAsh5357: Update again

2022-06-13T19:45:43Z

Update again

ChampionAsh5357: Update to 1.19

2022-06-11T17:05:12Z

Update to 1.19

ChampionAsh5357: Update to 1.17

2021-07-30T00:08:10Z

Update to 1.17

ShrimpBot: Categorize with Category:Common Concepts by SizableShrimp#0755

2021-05-19T00:59:01Z

Categorize with Category:Common Concepts by SizableShrimp#0755

Unbekannt: update Box to use new Templates

2020-12-21T13:48:35Z

update Box to use new Templates

SciWhiz12: Text replacement - "{{Colored box|title=Important|content=" to "{{Tip/Important|"

2020-12-20T22:03:30Z

Text replacement - "{{Colored box|title=Important|content=" to "{{Tip/Important|"

SciWhiz12: SciWhiz12 moved page Internalization to Internationalization without leaving a redirect: rename to correct name

2020-10-24T23:08:15Z

SciWhiz12 moved page Internalization to Internationalization without leaving a redirect: rename to correct name

SciWhiz12: first import from dokuwiki, and formatting fixes

2020-10-23T16:09:56Z

first import from dokuwiki, and formatting fixes

New page

'''Internationalization''' (shortened as '''i18n'''), is a way of designing code so that it requires no changes to be adapted for various languages. '''Localization''' (shortened as '''l10n''') is the process of adapting displayed text to the user’s language.

Internationalization is implemented using ''translation keys''. A translation key is a string that identifies a piece of displayable text in no specific language. For example, <code>block.minecraft.dirt</code> is the translation key referring to the name of the Dirt block. This way, displayable text may be referenced with no concern for a specific language. The code requires no changes to be adapted in a new language.

Localization will happen in the game’s locale. In a Minecraft client the locale is specified by the language settings. On a dedicated server, the only supported locale is <code>en_us</code>. A list of available locales can be found on the [https://minecraft.gamepedia.com/Language#Available_languages Minecraft Wiki].

{{Colored box|title=Important|content=The only purpose of a translation key is internationalization. Do not use them for logic, such as comparing if two blocks are equal. Use their [[Registration|registry names]] instead.}}

== Language files ==

Language files are located by <code>assets/[namespace]/lang/[locale].json</code> (e.g. the US English translation for <code>examplemod</code> would be <code>assets/examplemod/lang/en_us.json</code>). The file format is simply a json map from translation keys to values. The file must be encoded in UTF-8.

<syntaxhighlight lang="json">
{
"item.examplemod.example_item": "Example Item Name",
"block.examplemod.example_block": "Example Block Name",
"commands.examplemod.example_command.error": "Example Command Errored!"
}
</syntaxhighlight>

== Usage with Blocks and Items ==

Block, Item, and a few other Minecraft classes have built-in translation keys used to display their names. These translation keys are specified by overriding <code>getTranslationKey()</code>. Item also has <code>getTranslationKey(ItemStack)</code> which can be overridden to provide different translation keys depending on <code>ItemStack</code> NBT.

By default, <code>getTranslationKey()</code> will return <code>block</code> or <code>item</code>. prepended to the registry name of the block or item, with the colon replaced by a dot. <code>BlockItem</code>s will take their corresponding Block's translation key by default. For example, an item with ID <code>examplemod:example_item</code> effectively requires the following line in a language file:

<syntaxhighlight lang="json">
{
"item.examplemod.example_item": "Example Item Name"
}
</syntaxhighlight>

== Localization methods ==

{{Colored box|title=Important|content=A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.
<br/><br/>
To respect the language settings of clients, the server should have clients localize text in their own locale using <code>TranslationTextComponent</code> or other methods preserving the language neutral translation keys.}}

<h3 id="I18n"><tt style="font-size: 100%">net.minecraft.client.resources.I18n</tt></h3>

{{Colored box|background-title-color=#d4101c|title=Warning|content='''This I18n class can only be found on the [[Sides#Different_Kinds_of_Sides|physical client]]!''' It is intended to be used by code that only runs on the client. Attempts to use this on a server will throw exceptions and crash.}}

<code>format(String, Object...)</code> localizes in the client’s locale with formatting. The first parameter is a translation key, and the rest are formatting arguments for <code>String.format(String, Object...)</code>.

=== <tt style="font-size: 100%">TranslationTextComponent</tt> ===

<code>TranslationTextComponent</code> is an <code>ITextComponent</code> that is localized and formatted lazily. It is very useful when sending messages to players because it will be automatically localized in their own locale.

The first parameter of the <code>TranslationTextComponent(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>ITextComponent</code>s that will be inserted into the resulting formatted text with all their attributes preserved.

@@ Line 45: / Line 45: @@
 === <tt style="font-size: 100%">TranslatableContents</tt> ===
-<code>TranslatableContents</code> is a <code>ComponentContents</code> that is localized and formatted lazily. A <code>Component</code> can be created for this using <code>Component#translatable</code>. It is very useful when sending messages to players because it will be automatically localized in their own locale.
+<code>TranslatableContents</code> is a <code>ComponentContents</code> that is localized and formatted lazily. It is very useful when sending messages to players because it will be automatically localized in their own locale.
 The first parameter of the <code>TranslatableContents(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>Component</code>s that will be inserted into the resulting formatted text with all their attributes preserved.
 [[Category:Common Concepts]]

@@ Line 35: / Line 35: @@
 {{Tip/Important|A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.
 <br/><br/>
-To respect the language settings of clients, the server should have clients localize text in their own locale using <code>TranslatableComponent</code> or other methods preserving the language neutral translation keys.}}
+To respect the language settings of clients, the server should have clients localize text in their own locale using components with <code>TranslatableContents</code> or other methods preserving the language neutral translation keys.}}
 <h3 id="I18n"><tt style="font-size: 100%">net.minecraft.client.resources.language.I18n</tt></h3>
@@ Line 43: / Line 43: @@
 <code>get(String, Object...)</code> localizes in the client’s locale with formatting. The first parameter is a translation key, and the rest are formatting arguments for <code>String.format(String, Object...)</code>.
-=== <tt style="font-size: 100%">TranslatableComponent</tt> ===
+=== <tt style="font-size: 100%">TranslatableContents</tt> ===
-<code>TranslatableComponent</code> is a <code>Component</code> that is localized and formatted lazily. It is very useful when sending messages to players because it will be automatically localized in their own locale.
+<code>TranslatableContents</code> is a <code>ComponentContents</code> that is localized and formatted lazily. A <code>Component</code> can be created for this using <code>Component#translatable</code>. It is very useful when sending messages to players because it will be automatically localized in their own locale.
-The first parameter of the <code>TranslatableComponent(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>Component</code>s that will be inserted into the resulting formatted text with all their attributes preserved.
+The first parameter of the <code>TranslatableContents(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>Component</code>s that will be inserted into the resulting formatted text with all their attributes preserved.
 [[Category:Common Concepts]]

@@ Line 21: / Line 21: @@
 == Usage with Blocks and Items ==
-Block, Item, and a few other Minecraft classes have built-in translation keys used to display their names. These translation keys are specified by overriding <code>getTranslationKey()</code>. Item also has <code>getTranslationKey(ItemStack)</code> which can be overridden to provide different translation keys depending on <code>ItemStack</code> NBT.
+Block, Item, and a few other Minecraft classes have built-in translation keys used to display their names. These translation keys are specified by overriding <code>getDescriptionId()</code>. Item also has <code>getDescriptionId(ItemStack)</code> which can be overridden to provide different translation keys depending on <code>ItemStack</code> NBT.
-By default, <code>getTranslationKey()</code> will return <code>block</code> or <code>item</code>. prepended to the registry name of the block or item, with the colon replaced by a dot. <code>BlockItem</code>s will take their corresponding Block's translation key by default. For example, an item with ID <code>examplemod:example_item</code> effectively requires the following line in a language file:
+By default, <code>getDescriptionId()</code> will return <code>block</code> or <code>item</code>. prepended to the registry name of the block or item, with the colon replaced by a dot. <code>BlockItem</code>s will take their corresponding Block's translation key by default. For example, an item with ID <code>examplemod:example_item</code> effectively requires the following line in a language file:
 <syntaxhighlight lang="json">
@@ Line 35: / Line 35: @@
 {{Tip/Important|A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.
 <br/><br/>
-To respect the language settings of clients, the server should have clients localize text in their own locale using <code>TranslationTextComponent</code> or other methods preserving the language neutral translation keys.}}
+To respect the language settings of clients, the server should have clients localize text in their own locale using <code>TranslatableComponent</code> or other methods preserving the language neutral translation keys.}}
-<h3 id="I18n"><tt style="font-size: 100%">net.minecraft.client.resources.I18n</tt></h3>
+<h3 id="I18n"><tt style="font-size: 100%">net.minecraft.client.resources.language.I18n</tt></h3>
 {{Tip/Danger|'''This I18n class can only be found on the [[Sides#Different_Kinds_of_Sides|physical client]]!''' It is intended to be used by code that only runs on the client. Attempts to use this on a server will throw exceptions and crash.}}
-<code>format(String, Object...)</code> localizes in the client’s locale with formatting. The first parameter is a translation key, and the rest are formatting arguments for <code>String.format(String, Object...)</code>.
+<code>get(String, Object...)</code> localizes in the client’s locale with formatting. The first parameter is a translation key, and the rest are formatting arguments for <code>String.format(String, Object...)</code>.
-=== <tt style="font-size: 100%">TranslationTextComponent</tt> ===
+=== <tt style="font-size: 100%">TranslatableComponent</tt> ===
-<code>TranslationTextComponent</code> is an <code>ITextComponent</code> that is localized and formatted lazily. It is very useful when sending messages to players because it will be automatically localized in their own locale.
+<code>TranslatableComponent</code> is a <code>Component</code> that is localized and formatted lazily. It is very useful when sending messages to players because it will be automatically localized in their own locale.
-The first parameter of the <code>TranslationTextComponent(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>ITextComponent</code>s that will be inserted into the resulting formatted text with all their attributes preserved.
+The first parameter of the <code>TranslatableComponent(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>Component</code>s that will be inserted into the resulting formatted text with all their attributes preserved.
 [[Category:Common Concepts]]

← Older revision		Revision as of 00:59, 19 May 2021
Line 48:		Line 48:

	The first parameter of the <code>TranslationTextComponent(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>ITextComponent</code>s that will be inserted into the resulting formatted text with all their attributes preserved.		The first parameter of the <code>TranslationTextComponent(String, Object...)</code> constructor is a translation key, and the rest are used for formatting. The only supported format specifiers are <code>%s</code> and <code>%1$s</code>, <code>%2$s</code>, <code>%3$s</code> etc. Formatting arguments may be other <code>ITextComponent</code>s that will be inserted into the resulting formatted text with all their attributes preserved.
		+
		+
		+	[[Category:Common Concepts]]

@@ Line 5: / Line 5: @@
 Localization will happen in the game’s locale. In a Minecraft client the locale is specified by the language settings. On a dedicated server, the only supported locale is <code>en_us</code>. A list of available locales can be found on the [https://minecraft.gamepedia.com/Language#Available_languages Minecraft Wiki].
-{{Colored box|title=Important|content=The only purpose of a translation key is internationalization. Do not use them for logic, such as comparing if two blocks are equal. Use their [[Registration|registry names]] instead.}}
+{{Tip/Important|The only purpose of a translation key is internationalization. Do not use them for logic, such as comparing if two blocks are equal. Use their [[Registration|registry names]] instead.}}
 == Language files ==
@@ Line 33: / Line 33: @@
 == Localization methods ==
-{{Colored box|title=Important|content=A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.
+{{Tip/Important|A common issue is having the server localize for clients. The server can only localize in its own locale, which does not necessarily match the locale of connected clients.
 <br/><br/>
 To respect the language settings of clients, the server should have clients localize text in their own locale using <code>TranslationTextComponent</code> or other methods preserving the language neutral translation keys.}}

← Older revision	Revision as of 23:08, 24 October 2020
(No difference)