Create an API for plugin-defined text translations

Author: zml2008

src/main/java/org/spongepowered/api/entity/player/Player.java

@@ -31,7 +31,6 @@
 import org.spongepowered.api.resourcepack.ResourcePack;
 import org.spongepowered.api.scoreboard.Scoreboard;
 import org.spongepowered.api.text.Text;
-import org.spongepowered.api.text.translation.locale.Locales;
 import org.spongepowered.api.util.command.CommandSource;
 
 import java.util.Locale;
@@ -50,7 +49,6 @@ public interface Player extends Human, User, CommandSource, Viewer {
      * Gets the locale used by the player.
      *
      * @return The player's locale
-     * @see Locales
      */
     Locale getLocale();
 
@@ -87,7 +85,7 @@ public interface Player extends Human, User, CommandSource, Viewer {
      * @param reason The reason for the kick
      */
     void kick(Text.Literal reason);
-    
+
     /**
      * Gets the {@link Scoreboard} displayed to the player.
      *

src/main/java/org/spongepowered/api/text/TextFactory.java

@@ -24,6 +24,8 @@
  */
 package org.spongepowered.api.text;
 
+import java.util.Locale;
+
 /**
  * Represents the required implementation for the static methods in
  * {@link Texts}.
@@ -57,6 +59,16 @@ public interface TextFactory {
      */
     String toPlain(Text text);
 
+    /**
+     * Returns a plain text representation of the {@link Text} without any
+     * formatting in the provided Locale.
+     *
+     * @param text The text to convert
+     * @param locale The language to get the plain string in
+     * @return The text converted to plain text
+     */
+    String toPlain(Text text, Locale locale);
+
     /**
      * Returns a JSON representation of the {@link Text} as used in commands.
      *
@@ -65,6 +77,14 @@ public interface TextFactory {
      */
     String toJson(Text text);
 
+    /**
+     * Returns a JSON representation of the {@link Text} as used in commands in the specified language.
+     *
+     * @param text The text to convert
+     * @return The text converted to JSON
+     */
+    String toJson(Text text, Locale locale);
+
     /**
      * Returns the default legacy formatting character.
      *
@@ -111,4 +131,14 @@ public interface TextFactory {
      */
     String toLegacy(Text text, char code);
 
+    /**
+     * Returns a representation of the {@link Text} using the legacy color
+     * codes in the given Locale.
+     *
+     * @param text The text to convert
+     * @param code The legacy char to use for the message
+     * @return The text converted to the old color codes
+     */
+    String toLegacy(Text text, char code, Locale locale);
+
 }

src/main/java/org/spongepowered/api/text/translation/ResourceBundleTranslation.java

@@ -0,0 +1,86 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.text.translation;
+
+import com.google.common.base.Function;
+import com.google.common.base.Preconditions;
+
+import java.util.Locale;
+import java.util.ResourceBundle;
+
+/**
+ * A translation class designed to be used for ResourceBundles. For convenience, most users will want to wrap this in a class that keeps track of
+ * resource bundles. A simple implementaion would look like:
+ * <pre>
+ *     public class TranslationHelper {
+ *         private static final Function<Locale, ResourceBundle> LOOKUP_FUNC = new Function<Locale, ResourceBundle>() {
+ *             &at;Nullable
+ *             &at;Override
+ *             public ResourceBundle apply(Locale input) {
+ *                return ResourceBundle.getBundle("com.mydomain.myplugin.Translations", input);
+ *             }
+ *         };
+ *
+ *         private TranslationHelper() {} // Prevent instance creation
+ *
+ *         public static Text t(String key, Object... args) {
+ *             return Texts.of(new ResourceBundleTranslation(key, LOOKUP_FUNC), args);
+ *         }
+ *     }
+ *
+ * </pre>
+ */
+public class ResourceBundleTranslation implements Translation {
+    private final String key;
+    private final Function<Locale, ResourceBundle> bundleFunction;
+
+    public ResourceBundleTranslation(String key, Function<Locale, ResourceBundle> bundleFunction) {
+        this.key = key;
+        this.bundleFunction = bundleFunction;
+    }
+
+
+    @Override
+    public String getId() {
+        return this.key;
+    }
+
+    @Override
+    public String getName() {
+        return this.key;
+    }
+
+    @Override
+    public String get(Locale locale) {
+        Preconditions.checkNotNull(locale, "locale");
+        ResourceBundle bundle = this.bundleFunction.apply(locale);
+        return bundle == null ? this.key : bundle.getString(this.key);
+    }
+
+    @Override
+    public String get(Locale locale, Object... args) {
+        return String.format(locale, get(locale), args);
+    }
+}

src/main/java/org/spongepowered/api/text/translation/Translation.java

@@ -25,18 +25,21 @@
 package org.spongepowered.api.text.translation;
 
 import org.spongepowered.api.CatalogType;
-import org.spongepowered.api.text.translation.locale.Locales;
+
+import java.util.Locale;
 
 /**
  * Represents an identifier for text that can be translated into multiple
- * languages. This is usually sent directly to the client and translated there,
- * not on the server.
+ * languages. Minecraft-included translations are generally translated clientside.
+ * Translations not included in Minecraft are generally expected to
+ * be translated server-side, for example using Gettext or a
+ * {@link java.util.ResourceBundle}
  *
  * <p>Some translations require parameters to be sent together with them, if
  * they're not given they will be filled with empty text.</p>
  *
- * <p>While the client has multiple locales available, most implementations
- * support only {@link Locales#ENGLISH}.</p>
+ * <p>While the client has multiple locales available, server-side vanilla translations
+ * support only {@link Locale#ENGLISH}.</p>
  */
 public interface Translation extends CatalogType {
 
@@ -45,6 +48,7 @@ public interface Translation extends CatalogType {
      *
      * @return The translation identifier of this translation
      */
+    @Override
     String getId();
 
     /**
@@ -53,19 +57,13 @@ public interface Translation extends CatalogType {
      *
      * @return The default translation without any parameters
      */
-    String get();
+    String get(Locale locale);
 
     /**
      * Gets the default translation with the specified parameters.
      *
      * @param args The parameters for this translation
      * @return The default translation with the specified parameters
      */
-    String get(Object... args);
-
-    // This would only work on the client, the server has only the English
-    // translation
-    // String get(Locale locale);
-    // String get(Locale locale, Object... args);
-
+    String get(Locale locale, Object... args);
 }

src/main/java/org/spongepowered/api/text/translation/locale/Locales.java

@@ -22,4 +22,43 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-@org.spongepowered.api.util.annotation.NonnullByDefault package org.spongepowered.api.text.translation.locale;
+package org.spongepowered.api.util;
+
+import com.google.common.base.Function;
+import org.spongepowered.api.text.Text;
+import org.spongepowered.api.text.Texts;
+import org.spongepowered.api.text.translation.ResourceBundleTranslation;
+
+import java.util.Locale;
+import java.util.ResourceBundle;
+
+import javax.annotation.Nullable;
+
+/**
+ * This class provides translations for strings within SpongeAPI. Plugins should consult an implementaion of Translation for help.
+ */
+public class SpongeApiTranslationHelper {
+
+    private static final Function<Locale, ResourceBundle> LOOKUP_FUNC = new Function<Locale, ResourceBundle>() {
+        @Nullable
+        @Override
+        public ResourceBundle apply(Locale input) {
+            return ResourceBundle.getBundle("org.spongepowered.api.Translations", input);
+        }
+    };
+
+    private SpongeApiTranslationHelper() {
+    } // Prevent instance creation
+
+    /**
+     * Get the translated text for a given string.
+     *
+     * @param key The translation key
+     * @param args Translation parameters
+     * @return The translatable text
+     */
+    public static Text t(String key, Object... args) {
+        return Texts.of(new ResourceBundleTranslation(key, LOOKUP_FUNC), args);
+    }
+
+}