feat(l10n): document cloud-translations & clarify caption usage

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 `<key>`.
+The configured caption messages may contain placeholders, most often in the form `<key>`.
 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`](<https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/parsing/ParserException.html#formatCaption(org.incendo.cloud.caption.CaptionFormatter)>)
 or
 [`CommandContext#formatCaption`](<https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/context/CommandContext.html#formatCaption(org.incendo.cloud.caption.CaptionFormatter,org.incendo.cloud.caption.Caption,org.incendo.cloud.caption.CaptionVariable...)>).
+
+## 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<YourSenderType> extractor = yourSenderType::locale;
+// You then create the translation bundle, which is a CaptionProvider.
+TranslationBundle<YourSenderType> 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<YourSenderType> extractor = yourSenderType::locale;
+// You then create the translation bundle, which is a CaptionProvider.
+TranslationBundle<YourSenderType> 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<YourSenderType> extractor = yourSenderType::locale;
+// You then create the translation bundle, which is a CaptionProvider.
+TranslationBundle<YourSenderType> 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<YourSenderType> extractor = yourSenderType::locale;
+// You then create the translation bundle, which is a CaptionProvider.
+TranslationBundle<YourSenderType> bundle = VelocityTranslationBundle.velocity(extractor);
+// Then you register the caption provider.
+manager.captionRegistry().registerProvider(bundle);
+```