XWIKI-15140: Allow giving a chain of translations keys fallbacks to the localization script service

xwiki-platform-core/xwiki-platform-localization/xwiki-platform-localization-script/src/main/java/org/xwiki/localization/script/LocalizationScriptService.java

@@ -23,6 +23,7 @@
 import java.nio.charset.StandardCharsets;
 import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashSet;
 import java.util.Locale;
 import java.util.Set;
@@ -32,6 +33,7 @@
 import javax.inject.Provider;
 import javax.inject.Singleton;
 
+import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.io.LineIterator;
 import org.slf4j.Logger;
@@ -167,6 +169,16 @@ public String render(String key)
         return render(key, (Collection<?>) null);
     }
 
+    /**
+     * @param keys the translations keys to try one by one
+     * @return the rendered translation message
+     * @since 10.2
+     */
+    public String render(Collection<String> keys)
+    {
+        return render(keys, (Collection<?>) null);
+    }
+
     /**
      * @param key the translation key
      * @param locale the {@link Locale} for which this translation is searched. The result might me associated to a
@@ -181,6 +193,19 @@ public String render(String key, Locale locale)
         return render(key, (Collection<?>) null, locale);
     }
 
+    /**
+     * @param keys the translations keys to try one by one
+     * @param locale the {@link Locale} for which this translation is searched. The result might me associated to a
+     *            different {@link Locale} (for example getting the {@code fr} translation when asking for the
+     *            {@code fr_FR} one).
+     * @return the rendered translation message
+     * @since 10.2
+     */
+    public String render(Collection<String> keys, Locale locale)
+    {
+        return render(keys, (Collection<?>) null, locale);
+    }
+
     /**
      * @param key the translation key
      * @param parameters the translation parameters
@@ -191,6 +216,16 @@ public String render(String key, Collection<?> parameters)
         return render(key, Syntax.PLAIN_1_0, parameters);
     }
 
+    /**
+     * @param keys the translations keys to try one by one
+     * @param parameters the translation parameters
+     * @return the rendered translation message
+     */
+    public String render(Collection<String> keys, Collection<?> parameters)
+    {
+        return render(keys, Syntax.PLAIN_1_0, parameters);
+    }
+
     /**
      * @param key the translation key
      * @param parameters the translation parameters
@@ -206,6 +241,20 @@ public String render(String key, Collection<?> parameters, Locale locale)
         return render(key, Syntax.PLAIN_1_0, parameters);
     }
 
+    /**
+     * @param keys the translations keys to try one by one
+     * @param parameters the translation parameters
+     * @param locale the {@link Locale} for which this translation is searched. The result might me associated to a
+     *            different {@link Locale} (for example getting the {@code fr} translation when asking for the
+     *            {@code fr_FR} one).
+     * @return the rendered translation message
+     * @since 10.2
+     */
+    public String render(Collection<String> keys, Collection<?> parameters, Locale locale)
+    {
+        return render(keys, Syntax.PLAIN_1_0, parameters);
+    }
+
     /**
      * @param key the translation key
      * @param syntax the syntax in which to render the translation message
@@ -217,6 +266,17 @@ public String render(String key, Syntax syntax)
         return render(key, syntax, (Collection<?>) null);
     }
 
+    /**
+     * @param keys the translations keys to try one by one
+     * @param syntax the syntax in which to render the translation message
+     * @return the rendered translation message, the key if no translation can be found and null if the rendering failed
+     * @since 10.2
+     */
+    public String render(Collection<String> keys, Syntax syntax)
+    {
+        return render(keys, syntax, (Collection<?>) null);
+    }
+
     /**
      * @param key the translation key
      * @param syntax the syntax in which to render the translation message
@@ -232,6 +292,20 @@ public String render(String key, Syntax syntax, Locale locale)
         return render(key, syntax, (Collection<?>) null, locale);
     }
 
+    /**
+     * @param keys the translations keys to try one by one
+     * @param syntax the syntax in which to render the translation message
+     * @param locale the {@link Locale} for which this translation is searched. The result might me associated to a
+     *            different {@link Locale} (for example getting the {@code fr} translation when asking for the
+     *            {@code fr_FR} one).
+     * @return the rendered translation message, the key if no translation can be found and null if the rendering failed
+     * @since 10.2
+     */
+    public String render(Collection<String> keys, Syntax syntax, Locale locale)
+    {
+        return render(keys, syntax, (Collection<?>) null, locale);
+    }
+
     /**
      * @param key the translation key
      * @param syntax the syntax in which to render the translation message
@@ -243,6 +317,18 @@ public String render(String key, Syntax syntax, Collection<?> parameters)
         return render(key, syntax, parameters, this.localizationContext.getCurrentLocale());
     }
 
+    /**
+     * @param keys the translations keys to try one by one
+     * @param syntax the syntax in which to render the translation message
+     * @param parameters the translation parameters
+     * @return the rendered translation message, the key if no translation can be found and null if the rendering failed
+     * @since 10.2
+     */
+    public String render(Collection<String> keys, Syntax syntax, Collection<?> parameters)
+    {
+        return render(keys, syntax, parameters, this.localizationContext.getCurrentLocale());
+    }
+
     /**
      * @param key the translation key
      * @param syntax the syntax in which to render the translation message
@@ -256,7 +342,34 @@ public String render(String key, Syntax syntax, Collection<?> parameters)
      */
     public String render(String key, Syntax syntax, Collection<?> parameters, Locale locale)
     {
-        Translation translation = this.localization.getTranslation(key, locale);
+        return render(Collections.singletonList(key), syntax, parameters, locale);
+    }
+
+    /**
+     * @param keys the translations keys to try one by one
+     * @param syntax the syntax in which to render the translation message
+     * @param parameters the translation parameters
+     * @param locale the {@link Locale} for which this translation is searched. The result might me associated to a
+     *            different {@link Locale} (for example getting the {@code fr} translation when asking for the
+     *            {@code fr_FR} one).
+     * @return the rendered translation message, the key if no translation can be found and null if the rendering failed
+     * @since 10.2
+     */
+    public String render(Collection<String> keys, Syntax syntax, Collection<?> parameters, Locale locale)
+    {
+        if (CollectionUtils.isEmpty(keys)) {
+            return null;
+        }
+
+        Translation translation = null;
+
+        for (String key : keys) {
+            translation = this.localization.getTranslation(key, locale);
+
+            if (translation != null) {
+                break;
+            }
+        }
 
         String result;
 
@@ -279,7 +392,7 @@ public String render(String key, Syntax syntax, Collection<?> parameters, Locale
                 result = null;
             }
         } else {
-            result = key;
+            result = keys.iterator().next();
         }
 
         return result;

xwiki-platform-core/xwiki-platform-localization/xwiki-platform-localization-script/src/test/java/org/xwiki/localization/script/LocalizationScriptServiceTest.java

@@ -112,24 +112,32 @@ public Object answer(InvocationOnMock invocation) throws Throwable
     public void render() throws Exception
     {
         assertEquals("print result", localizationScriptService.render("key"));
+        assertEquals("print result",
+            localizationScriptService.render(Arrays.asList("not existing key", "key", "another key")));
     }
 
     @Test
     public void renderWithSyntax() throws Exception
     {
         assertEquals("print result", localizationScriptService.render("key", Syntax.PLAIN_1_0));
+        assertEquals("print result", localizationScriptService
+            .render(Arrays.asList("not existing key", "key", "another key"), Syntax.PLAIN_1_0));
     }
 
     @Test
     public void renderWithSyntaxAndParameters() throws Exception
     {
         assertEquals("print result", localizationScriptService.render("key", Syntax.PLAIN_1_0, Arrays.asList()));
+        assertEquals("print result", localizationScriptService
+            .render(Arrays.asList("not existing key", "key", "another key"), Syntax.PLAIN_1_0, Arrays.asList()));
     }
 
     @Test
     public void renderWithParameters() throws Exception
     {
         assertEquals("print result", localizationScriptService.render("key", Arrays.asList()));
+        assertEquals("print result",
+            localizationScriptService.render(Arrays.asList("not existing key", "key", "another key"), Arrays.asList()));
     }
 
     @Test
@@ -142,8 +150,8 @@ public void getCurrentLocale() throws Exception
     @Test
     public void getAvailableLocales() throws Exception
     {
-        when(environment.getResourceAsStream(eq("/WEB-INF/xwiki-locales.txt"))).thenReturn(
-                getClass().getResourceAsStream("/xwiki-locales.txt"));
+        when(environment.getResourceAsStream(eq("/WEB-INF/xwiki-locales.txt")))
+            .thenReturn(getClass().getResourceAsStream("/xwiki-locales.txt"));
         Set<Locale> locales = localizationScriptService.getAvailableLocales();
         assertNotNull(locales);
         assertFalse(locales.isEmpty());