Create an API for plugin-defined text translations

[zml2008]

This PR expands the translatable interface to be more friendly to server-side translations. It also lays the groundwork for making every string in SpongeAPI translatable. This API moves the change from untranslated string to translated string from wherever the Text is created to directly before the text is sent to the CommandSource.

Miecraft's resource pack client-side strings are still supported, but not recommended because usage is more complicated.

[stephan-gh]

Why have you removed Locales?

[octylFractal]

The built-in Java Locale is sufficient, Fields

[stephan-gh]

@kenzierocks This list contains an exact and unlike Java's also complete list of locales available in Minecraft, which can be used to detect the language the client is using

[octylFractal]

True. Can we have those be set to constants instead of null, then? It seems they would be equal across all implementations.

[zml2008]

@Minecrell that's called player.getLocale()... And the complete list of locales available is in some standards document somewhere. I don't really see any use cases for maintaining a list of possible MC languages.

[stephan-gh]

@zml player.getLocale() returns the player's currently selected Minecraft locale, which can be - unless added by resource packs - only one of these in the list. You could find a lot of parts in the API you could remove with the reason "a complete list is available somewhere". The Minecraft wiki maintains lists for most things available in Minecraft.

At the end, we're creating an API that's supposed to be easily usable, so providing additional convenience for the API user is nothing bad. With this class you don't need to Google first, you can simply check the player's locale from one of the default locales available in Minecraft.

As a side note: some of the Minecraft locales are not standardized, because there are no exact specifications for some languages. Due to this, Minecraft has also changed locale codes in the past which would result in breaking plugins which is definitely something we want to prevent as much as possible. Maintaining this list (actually generated automatically from Minecraft's resource index) requires almost no effort together with a Minecraft update, but additional effort from plugin developers without this automation.

Additionally I think this removal is really out of scope for a PR for plugin-defined translations, this should be discussed in a separate issue.

[zml2008]

is there an instance in which this list would be actually be used? Because I can't think of any?
(and if MC changes locale codes, we can add mappings then. but in general no mappings are needed.)

[stephan-gh]

If implemented properly you can use it like player.getLocale() == Locales.PIRATE_ENGLISH or registry.getTranslation("translation.test.none").get(Locales.KLINGON) (which would only work on the client)

[zml2008]

However, nobody should be using fixed locales. You'd never get a translation for a specific Locale, you almost never compare a locale using the Locale instance (instead using its toString to get a strings file) -- your use cases are not particularly realistic.

[stephan-gh]

Simply because it does not seem useful if you code a generic, well configurable plugin does not mean there are no use cases at all. For custom plugins there are often things hardcoded that are really unlikely to change, and even if you just use it for debugging. Keep in mind in theory you could also use it for a configuration to provide an easier way to configure locales with the name instead of their locale codes.

[zml2008]

so you're saying just because it's not useful for well-written plugins, it might be useful for badly-written plugins? Why should we be supporting anything but well-written plugins?

[stephan-gh]

@zml2008 This discussion is getting more and more off-topic, you can't see "well-written" plugins from a generalized view, it always depends on which environment and which people a plugin is developed for. For a custom plugin where direct configuration isn't that important (as it will almost never change) implementing a complex configuration would be wasted time. Just because something is hard-coded, doesn't directly mean it's not a "well-written" plugin.

As for the removal of Locales, this is really out of scope for this PR so feel free to open another issue so we can discuss this any further. At the end, it doesn't hurt if this stays in the API just because it doesn't have many use(r)s. I'm sure there will be situations where people will be glad when they can simply test with the Locales directly instead of having to find out the exact locale code mapping as used in Minecraft first.

[zml2008]

You know you still haven't given any specific use cases for this. Every program that supports localizations does it through resource files. We have the advantage of having Java's standard library which has user-friendly name mappings for most Locales, and resource file lookup is done using the locale codes.

Anyway, special-purpose plugins that you're referring to generally don't have localizations at all -- having a translated plugin at all requires a multilingual dev and/or a large enough audience to crowdsource translations.

I don't really see the point in splitting this into a separate PR at this point -- might as well just go for a yes/no on keeping Locales @Zidane?

[ST-DDT]

How does the server detect whether the translation is (or supposted to be) included in the minecraft client?
Some full mods (client and server) may want to resolve the text client side because they also provide resourcepacks. There should probably an interface or a method whether the translation should be resolved on the server side. An internal Set of keys could work as well, but mods should be able to add to it.

[zml2008]

mods with resource packs get translations from the GameRegistry. Those are clientside translations. Anything doing serverside translations uses a different Translation implementation appropriate to its translation store.

[progwml6]

@zml2008 how are we going to handle the eventual addition of client side plugins?
as these might have additional translations that aren't serverside

[zml2008]

They can either have resource bundles clientside and use translation instances from the GameRegistry (which still do translations clientside, since we don't have all languages serverside), or have all messages in a ResourceBundle and just do the translations on whatever side the code that sends the message is on (I don't think there's much/any client->server sending of translation strings though).

[stephan-gh]

I think we should keep the getters without language to get it in the default language of the server (which is also the same as used in Texts.toPlain(Text) without locale argument)

[maxov]

Should add @see SpongeTranslationHelper for example impl instead of copying it inline

[zml2008]

SpongeTranslationHelper will probably be switched over to gettext once the necessary tooling is ready, so probably not good to point to it in the docs for the resource bundle implementation.