Merge pull request #72 from salesforce/add-basque

add Basque language support

Author: yoikawa

pom.xml

@@ -3,7 +3,7 @@
 
   <groupId>com.salesforce.grammaticus</groupId>
   <artifactId>grammaticus</artifactId>
-  <version>1.2.32-SNAPSHOT</version>
+  <version>1.3.0-SNAPSHOT</version>
   <packaging>jar</packaging>
 
   <name>Grammaticus</name>
@@ -41,12 +41,9 @@
   </developers>
 
   <properties>
-    <maven.compiler.release>11</maven.compiler.release>
+    <java.version>17</java.version>
+    <maven.compiler.release>17</maven.compiler.release>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <icu4j.version>75.1</icu4j.version>
-    <icu4j-localespi.version>75.1</icu4j-localespi.version>
-    <picocli.version>4.1.4</picocli.version>
-    <caffeine.version>2.8.0</caffeine.version>
   </properties>
 
   <profiles>
@@ -75,10 +72,11 @@
           </plugin>
           <plugin>
             <artifactId>maven-surefire-plugin</artifactId>
-            <version>3.0.0-M8</version>
+            <version>3.2.5</version>
             <configuration>
               <!-- suppress all loggings for unit test -->
               <argLine>@{argLine} -Djava.util.logging.config.file=src/test/resources/logging.properties -Dpolyglot.engine.WarnInterpreterOnly=false</argLine>
+              <useModulePath>false</useModulePath>
             </configuration>
           </plugin>
           <plugin>
@@ -270,38 +268,64 @@
     <dependency>
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
-      <version>33.4.0-jre</version>
+      <version>33.4.8-jre</version>
     </dependency>
 
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
-      <version>4.13.1</version>
+      <version>4.13.2</version>
+      <scope>test</scope>
+    </dependency>
+
+    <!-- JUnit 5 (Jupiter) and Vintage to keep JUnit 4 tests working -->
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <version>5.10.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-params</artifactId>
+      <version>5.10.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <version>5.10.2</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.vintage</groupId>
+      <artifactId>junit-vintage-engine</artifactId>
+      <version>5.10.2</version>
       <scope>test</scope>
     </dependency>
 
     <dependency>
       <groupId>com.ibm.icu</groupId>
       <artifactId>icu4j</artifactId>
-      <version>${icu4j.version}</version>
+      <version>75.1</version>
     </dependency>
 
     <dependency>
       <groupId>com.ibm.icu</groupId>
       <artifactId>icu4j-localespi</artifactId>
-      <version>${icu4j-localespi.version}</version>
+      <version>75.1</version>
       <optional>true</optional>
     </dependency>
 
     <dependency>
       <groupId>com.github.ben-manes.caffeine</groupId>
       <artifactId>caffeine</artifactId>
-      <version>${caffeine.version}</version>
+      <version>3.2.2</version>
     </dependency>
     <dependency>
       <groupId>com.github.ben-manes.caffeine</groupId>
       <artifactId>guava</artifactId>
-      <version>${caffeine.version}</version>
+      <version>3.1.7</version>
     </dependency>
 
     <dependency>
@@ -314,7 +338,7 @@
     <dependency>
       <groupId>info.picocli</groupId>
       <artifactId>picocli</artifactId>
-      <version>${picocli.version}</version>
+      <version>4.1.4</version>
       <scope>test</scope>
     </dependency>
     <dependency>

src/main/java/com/force/i18n/LabelUtils.java

@@ -32,8 +32,6 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
-import org.checkerframework.checker.nullness.qual.Nullable;
-
 import com.force.i18n.commons.text.GenericTrieMatcher;
 import com.force.i18n.commons.text.GenericTrieMatcher.GenericTrieMatch;
 import com.force.i18n.commons.text.TextUtil;
@@ -134,7 +132,7 @@ public String getPublicString(GrammaticalLabelSet labelSet, String section, Stri
      * @param grammar XML snippet
      * @return a sample dictionary file containing the xml snippet inside the "names" tag
      */
-    public static String getSampleGrammarFile(@Nullable String grammar) {
+    public static String getSampleGrammarFile(String grammar) {
         if (grammar == null || grammar.isEmpty()) {
             return null;
         } else {

src/main/java/com/force/i18n/grammar/LanguageCase.java

@@ -57,6 +57,7 @@ public enum LanguageCase {
     ADVERBIAL ("adv", "Adverbial"),
     ABESSIVE("abe", "Abessive"),
     COMITATIVE("com", "Comitative"),
+    BENEFACTIVE("be", "Benefactive"),
     ;
 
 	public static final char JSON_ATTR_NAME = 'c';

src/main/java/com/force/i18n/grammar/LanguageDeclension.java

@@ -361,11 +361,57 @@ default NounForm getNounForm(LanguageNumber number, LanguageArticle articleType)
         return getApproximateNounForm(number, getDefaultCase(), LanguagePossessive.NONE, articleType);
     }
 
+    /**
+     * Canonical noun form used by dictionary fallback copy. For languages with
+     * specialized concrete forms (e.g., Basque), this returns the appropriate
+     * enum-backed form to store values against. Defaults to getNounForm.
+     */
+    default NounForm getCanonicalNounForm(LanguageNumber number, LanguageArticle articleType) {
+        return getNounForm(number, articleType);
+    }
+
     // Convenience method for retrieving an equivalent nounForm from this declension
     default NounForm getNounForm(NounForm nf) {
         return getExactNounForm(nf.getNumber(), nf.getCase(), nf.getPossessive(), nf.getArticle());
     }
 
+    /**
+     * Hint for label parsing: whether to choose approximate/dynamic noun forms at <b>parse time</b>
+     * (not at render time) when constructing noun refs from labels.
+     * <p>
+     * Rationale: For languages whose inflection is primarily realized by productive rules at render time
+     * (e.g., generated from a bare stem using case/number/article morphology), the parser should preserve
+     * the requested attributes (number, case, article) by selecting a dynamic/approximate noun form and
+     * storing it directly in the tag. This avoids re-deriving or collapsing the author-requested attributes
+     * later, and prevents double approximation.
+     * </p>
+     * <p>
+     * If this method returns {@code true}, callers retrieving a noun tag's form should use that stored form
+     * as-is instead of recomputing an approximate form at render time.
+     * </p>
+     */
+    default boolean shouldApproximateNounFormsAtParseTime() { return false; }
+
+    /**
+     * Optional: Generate a rendered <b>surface</b> (the final, inflected output string) from a
+     * base/lemma value for the given noun form. Implementations may apply language-specific
+     * morphology and phonological adjustments (e.g., suffix selection, vowel interaction) based on
+     * the form's attributes (number, case, article, etc.).
+     * <p>
+     * Return {@code null} if surface generation from base is not supported by the declension.
+     * </p>
+     */
+    default String generateSurfaceFromBase(String base, NounForm form) { return null; }
+
+    /**
+     * Optional: Generate a rendered <b>surface</b> directly from a noun term for the given noun form.
+     * Default implementation delegates to {@link #generateSurfaceFromBase(String, NounForm)} using the
+     * term's default/base value.
+     */
+    default String generateSurfaceFromTerm(Noun noun, NounForm form) {
+        return generateSurfaceFromBase(noun == null ? null : noun.getDefaultString(false), form);
+    }
+
     /**
      * @return the maximum distance to look for modifiers associated with the noun
      * For languages without spaces between works, this should be 0

src/main/java/com/force/i18n/grammar/Noun.java

@@ -42,8 +42,8 @@ public abstract class Noun extends GrammaticalTerm implements Cloneable {
     private final NounType nounType;
     private String entityName;              // not final for readResolve()
     private String pluralAlias;             // not final for readResolve()
-    private LanguageGender gender;          // TODO: make final
-    private LanguageStartsWith startsWith;  // TODO: make final
+    private LanguageGender gender;
+    private LanguageStartsWith startsWith;
     private String access;                  // not final for readResolve()
     private final boolean isStandardField; // specifies whether this label is a standard field or not. For the Rename
     private final boolean isCopied;        // specifies whether this noun was copied from english (or another fallback language)
@@ -175,10 +175,9 @@ protected boolean equalsValue(Noun n) {
     }
 
     @Override
-    public final boolean equals(Object obj) {
+    public boolean equals(Object obj) {
         if (this == obj) return true;
-        if (obj instanceof Noun) {
-            Noun n = (Noun)obj;
+        if (obj instanceof Noun n) {
             return super.equals(n) && equalsAttribute(n) && equalsValue(n);
         }
         return false;