diff --git a/docs/localization/index.md b/docs/localization/index.md index 3ec8709..c87e64c 100644 --- a/docs/localization/index.md +++ b/docs/localization/index.md @@ -9,6 +9,8 @@ uses the [`Caption`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/caption/Caption.html) system. A [`Caption`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/caption/Caption.html) is a key to a configurable message, which allows you to override the default messages on a per-sender level. +The default messages are simple strings, but it's possible to use a custom [formatter](#formatting) to format +the messages into rich objects. The messages retrieved using caption providers that are registered to the command manager's [`CaptionRegistry`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/caption/CaptionRegistry.html). @@ -46,7 +48,7 @@ The platform adapters may include additional captions. See the platform-specific #### Formatting -Captions may contain placeholders, most often in the form ``. +The configured caption messages may contain placeholders, most often in the form ``. The JavaDoc for the caption keys list the available placeholders for the caption. The message registered for the caption will have those variables replaced with variables specific to the parser. @@ -60,3 +62,68 @@ type by invoking [`ParserException#formatCaption`]() or [`CommandContext#formatCaption`](). + +## Translations + +[`cloud-translations`](https://github.com/incendo/cloud-translations) contains community-contributed translations of the [captions](#captions) +used in the official Cloud modules. You may see the translation progress (and also contribute) yourself at +our [Crowdin](https://crowdin.com/project/incendo-cloud) page. + +### Usage + +These modules are available on [Maven Central](https://search.maven.org/search?q=g:org.incendo%20AND%20a:cloud-translations-*). + +#### [cloud-translations-core](https://github.com/Incendo/cloud-translations/tree/main/cloud-translations-core) + +This module contains tooling for creating caption providers from files with translations. +The module also contains translations for the captions in `cloud-core`. + +```java title="Registration of cloud-core translations" +// You need to create an extractor which maps the sender type to a locale. +LocaleExtractor extractor = yourSenderType::locale; +// You then create the translation bundle, which is a CaptionProvider. +TranslationBundle bundle = TranslationBundle.core(extractor); +// Then you register the caption provider. +manager.captionRegistry().registerProvider(bundle); +``` + +#### Minecraft Modules + +##### [cloud-translations-bukkit](https://github.com/Incendo/cloud-translations/tree/main/cloud-translations-bukkit) + +This module contains translations for the captions in `cloud-bukkit`. + +```java title="Registration of cloud-bukkit translations" +// You need to create an extractor which maps the sender type to a locale. +LocaleExtractor extractor = yourSenderType::locale; +// You then create the translation bundle, which is a CaptionProvider. +TranslationBundle bundle = BukkitTranslationBundle.bukkit(extractor); +// Then you register the caption provider. +manager.captionRegistry().registerProvider(bundle); +``` + +##### [cloud-translations-bungee](https://github.com/Incendo/cloud-translations/tree/main/cloud-translations-bungee) + +This module contains translations for the captions in `cloud-bungee`. + +```java title="Registration of cloud-bungee translations" +// You need to create an extractor which maps the sender type to a locale. +LocaleExtractor extractor = yourSenderType::locale; +// You then create the translation bundle, which is a CaptionProvider. +TranslationBundle bundle = BungeeTranslationBundle.bungee(extractor); +// Then you register the caption provider. +manager.captionRegistry().registerProvider(bundle); +``` + +##### [cloud-translations-velocity](https://github.com/Incendo/cloud-translations/tree/main/cloud-translations-velocity) + +This module contains translations for the captions in `cloud-velocity`. + +```java title="Registration of cloud-velocity translations" +// You need to create an extractor which maps the sender type to a locale. +LocaleExtractor extractor = yourSenderType::locale; +// You then create the translation bundle, which is a CaptionProvider. +TranslationBundle bundle = VelocityTranslationBundle.velocity(extractor); +// Then you register the caption provider. +manager.captionRegistry().registerProvider(bundle); +```