Bundles
Translation bundles are Java resource bundles containing your project's translation files. These files are organised into directories, with individual files representing a single locale, as well as a set of fallback translations to use when nothing exists for a given locale.
Structure
Translation bundles are represented by a directory and file structure in your project's resources, which are eventually
built into your project's distribution.
Generally, your project's resource files should be placed in src/main/resources/, though this may differ depending on
your build scripts.
You must place all translation bundles under a common base directory, represented by your
configured default bundle prefix, which defaults to translations.
These bundles must then have their own folder, as well as a filename prefix that groups them together, represented as
a bundle name — a string, split with the . character.
For example, if you're using translations as your default bundle prefix, your bundle is named example.strings,
and it contains .properties files, then your file structure might look like this:
src/main/resources/translations/example/strings.properties(Fallback translations)strings_de.properties(German)strings_es.properties(Spanish)strings_es_AR.properties(Spanish, Argentina)strings_fr.properties(French)strings_fr_CA.properties(French, Canada)
The files in your translation bundle must be in one of the supported file formats, or use a custom format you've created an adapter for. You'll also need to specify the message format it uses.
Override Bundles
If your project loads plugins or otherwise interacts with third-party code, it may be useful to allow other developers
to override the translations you've provided.
They can do this by shipping their own bundle, with the same name as yours, but with _override appended to the name.
For example, if your bundle is named example.strings, another developer can provide a bundle named
example.strings_override.
This override bundle should only contain the translations the developer wishes to override — any strings missing from
the override bundle will fall back to the original strings.
Using our previous example, if a developer wanted to override a string named commands.slap in the Canadian French
bundle, they could place that string in this resource file: translations/example/strings_override_fr_CA.properties
API
Translation bundles are represented by Bundle objects in code.
Generally speaking, you don't need to create your own Bundle objects, as they're generated by the
Gradle plugin and our code generators.
These Bundle objects are serialisable using kotlinx.serialiation,
with an API surface allowing you to retrieve their configuration data.
Properties
This bundle's class-loader, which usually refers to the generated translation class's class-loader.
If the "use class class-loader" option was disabled when generating the translation class, this will be the system class-loader instead.
String identifier representing this bundle's file format.
Use the getFileFormat() function to retrieve the corresponding FileFormat object.
String identifier representing this bundle's message format.
Use the getMessageFormat() function to retrieve the corresponding MessageFormat object.
This bundle's name, which is used when looking it up in the resource files.
Functions
Retrieve the FileFormat object represented by the identifier in the fileFormat property, or throw an
IllegalStateException if it can't be found.
Retrieve the MessageFormat object represented by the identifier in the messageFormat property, or throw an
IllegalStateException if it can't be found.
Retrieve the Control object for the FileFormat returned by the getFileFormat() function, or throw an
IllegalStateException if the FileFormat can't be found.
Returns a string of the form: Bundle $name/$fileFormat/$messageFormat