Issue #7593: Update doc for translation

checkstyle · Mar 26, 2023 · 08aa857 · 08aa857
1 parent 49b8305
commit 08aa857
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 40 deletions.
diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/TranslationCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/TranslationCheck.java
@@ -128,59 +128,93 @@
  * </li>
  * </ul>
  * <p>
+ * Note, that files with the same path and base name but which have different
+ * extensions will be considered as files that belong to different resource bundles.
+ * </p>
+ * <p>
  * To configure the check to check only files which have '.properties' and
  * '.translations' extensions:
  * </p>
  * <pre>
  * &lt;module name="Translation"&gt;
  *   &lt;property name="fileExtensions" value="properties, translations"/&gt;
+ *   &lt;property name="requiredTranslations" value="fr"/&gt;
  * &lt;/module&gt;
  * </pre>
  * <p>
- * Note, that files with the same path and base name but which have different
- * extensions will be considered as files that belong to different resource bundles.
+ * Example:
  * </p>
+ * <pre>
+ * #messages.properties
+ * hello=Hello
+ * cancel=Cancel
+ *
+ * #messages.translations
+ * hello=Hallo
+ * ok=OK
+ * </pre>
+ * <pre>
+ * messages.properties: Properties file 'messages_fr.properties' is missing.
+ * messages.translations: Properties file 'messages_fr.translations' is missing.
+ * </pre>
  * <p>
  * An example of how to configure the check to validate only bundles which base
  * names start with "ButtonLabels":
  * </p>
  * <pre>
  * &lt;module name="Translation"&gt;
  *   &lt;property name="baseName" value="^ButtonLabels.*$"/&gt;
+ *   &lt;property name="requiredTranslations" value="fr"/&gt;
  * &lt;/module&gt;
  * </pre>
  * <p>
- * To configure the check to check existence of Japanese and French translations:
+ * Example:
  * </p>
  * <pre>
- * &lt;module name="Translation"&gt;
- *   &lt;property name="requiredTranslations" value="ja, fr"/&gt;
- * &lt;/module&gt;
+ * #ButtonLabels.properties
+ * hello=Hello
+ * cancel=Cancel
+ *
+ * #ButtonLabels_fr.properties
+ * hello=Bonjour
+ * name=Nom
+ * </pre>
+ * <pre>
+ * ButtonLabels.properties: Key 'name' is missing.
+ * ButtonLabels_fr.properties: Key 'cancel' is missing.
  * </pre>
  * <p>
- * The following example shows how the check works if there is a message bundle
- * which element name contains language code, county code, platform name.
- * Consider that we have the below configuration:
+ * To configure the check to check existence of Japanese and French translations:
  * </p>
  * <pre>
  * &lt;module name="Translation"&gt;
- *   &lt;property name="requiredTranslations" value="es, fr, de"/&gt;
+ *   &lt;property name="requiredTranslations" value="ja, fr"/&gt;
  * &lt;/module&gt;
  * </pre>
  * <p>
- * As we can see from the configuration, the TranslationCheck was configured
- * to check an existence of 'es', 'fr' and 'de' translations. Let's assume that
- * we have the resource bundle:
+ * Example:
  * </p>
  * <pre>
- * messages_home.properties
- * messages_home_es_US.properties
- * messages_home_fr_CA_UNIX.properties
+ * #messages.properties
+ * hello=Hello
+ * cancel=Cancel
+ *
+ * #messages_ja.properties
+ * greeting=こんにちは
+ * age=年齢
+ *
+ * #messages_fr.properties
+ * greeting=Bonjour
+ * name=Nom
+ * </pre>
+ * <pre>
+ * messages.properties: Key 'age' missing.
+ * messages.properties: Key 'name' missing.
+ * messages_fr.properties: Key 'age' missing.
+ * messages_fr.properties: Key 'cancel' missing.
+ * messages_ja.properties: Key 'cancel' missing.
+ * messages_ja.properties: Key 'name' missing.
  * </pre>
- * <p>
- * Than the check will rise the following violation: "0: Properties file
- * 'messages_home_de.properties' is missing."
- * </p>
  * <p>
  * Parent is {@code com.puppycrawl.tools.checkstyle.Checker}
  * </p>

diff --git a/src/xdocs/config_misc.xml b/src/xdocs/config_misc.xml
@@ -2340,29 +2340,62 @@ messages.properties: Key 'ok' missing.
       </subsection>
 
       <subsection name="Examples" id="Translation_Examples">
+        <p>
+          Note, that files with the same path and base name but which have different
+          extensions will be considered as files that belong to different resource bundles.
+        </p>
         <p>
           To configure the check to check only files which have '.properties' and '.translations'
           extensions:
         </p>
         <source>
 &lt;module name=&quot;Translation&quot;&gt;
   &lt;property name=&quot;fileExtensions&quot; value=&quot;properties, translations&quot;/&gt;
+  &lt;property name=&quot;requiredTranslations&quot; value=&quot;fr&quot;/&gt;
 &lt;/module&gt;
         </source>
         <p>
-          Note, that files with the same path and base name but which have different
-          extensions will be considered as files that belong to different resource bundles.
+          Example:
         </p>
+        <source>
+#messages.properties
+hello=Hello
+cancel=Cancel
+
+#messages.translations
+hello=Hallo
+ok=OK
+        </source>
+        <source>
+messages.properties: Properties file 'messages_fr.properties' is missing.
+messages.translations: Properties file 'messages_fr.translations' is missing.
+        </source>
         <p>
           An example of how to configure the check to validate only bundles which base names
           start with "ButtonLabels":
         </p>
         <source>
 &lt;module name=&quot;Translation&quot;&gt;
   &lt;property name=&quot;baseName&quot; value=&quot;^ButtonLabels.*$&quot;/&gt;
+  &lt;property name=&quot;requiredTranslations&quot; value=&quot;fr&quot;/&gt;
 &lt;/module&gt;
         </source>
+        <p>
+          Example:
+        </p>
+        <source>
+#ButtonLabels.properties
+hello=Hello
+cancel=Cancel
 
+#ButtonLabels_fr.properties
+hello=Bonjour
+name=Nom
+        </source>
+        <source>
+ButtonLabels.properties: Key 'name' is missing.
+ButtonLabels_fr.properties: Key 'cancel' is missing.
+        </source>
         <p>
           To configure the check to check existence of Japanese and French translations:
         </p>
@@ -2372,29 +2405,29 @@ messages.properties: Key 'ok' missing.
 &lt;/module&gt;
         </source>
         <p>
-          The following example shows how the check works if there is a message bundle which
-          element name contains language code, county code, platform name.
-          Consider that we have the below configuration:
+          Example:
         </p>
         <source>
-&lt;module name=&quot;Translation&quot;&gt;
-  &lt;property name=&quot;requiredTranslations&quot; value=&quot;es, fr, de&quot;/&gt;
-&lt;/module&gt;
+#messages.properties
+hello=Hello
+cancel=Cancel
+
+#messages_ja.properties
+greeting=こんにちは
+age=年齢
+
+#messages_fr.properties
+greeting=Bonjour
+name=Nom
         </source>
-        <p>
-          As we can see from the configuration, the TranslationCheck was configured to check
-          an existence of 'es', 'fr' and 'de' translations. Let's assume that we have the resource
-          bundle:
-        </p>
         <source>
-messages_home.properties
-messages_home_es_US.properties
-messages_home_fr_CA_UNIX.properties
+messages.properties: Key 'age' missing.
+messages.properties: Key 'name' missing.
+messages_fr.properties: Key 'age' missing.
+messages_fr.properties: Key 'cancel' missing.
+messages_ja.properties: Key 'cancel' missing.
+messages_ja.properties: Key 'name' missing.
         </source>
-        <p>
-          Than the check will rise the following violation:
-          "0: Properties file 'messages_home_de.properties' is missing."
-        </p>
       </subsection>
 
       <subsection name="Example of Usage" id="Translation_Example_of_Usage">