Merge #788

788: Language settings & search parameter support for Java client r=curquiza a=Barabasbalazs

# Pull Request

## Related issue
Fixes #770

## What does this PR do?
- Implements support for the _localizedAttributes_ setting, _locales_ search parameter and updates the tests accordingly.

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


Co-authored-by: Balazs Barabas <barabas.balazska@gmail.com>
Co-authored-by: Clémentine <clementine@meilisearch.com>

.code-samples.meilisearch.yaml

@@ -837,3 +837,18 @@ distinct_attribute_guide_filterable_1: |-
 distinct_attribute_guide_distinct_parameter_1: |-
   SearchRequest searchRequest = SearchRequest.builder().q("white shirt").distinct("sku").build();
   client.index("products").search(searchRequest);
+search_parameter_reference_locales_1: |-
+  SearchRequest searchRequest = SearchRequest.builder().q("QUERY TEXT IN JAPANESE").locales(new String[]{"jpn"}).build();
+  client.index("INDEX_NAME").search(searchRequest);
+get_localized_attribute_settings_1: |-
+  client.index("INDEX_NAME").getLocalizedAttributesSettings();
+update_localized_attribute_settings_1: |-
+  LocalizedAttribute attribute = new LocalizedAttribute();
+  attribute.setAttributePatterns(new String[] {"jpn"});
+  attribute.setLocales(new String[] {"*_ja"});
+
+  client.index("INDEX_NAME").updateLocalizedAttributesSettings(
+    new LocalizedAttributes[] {attribute}
+  );
+reset_localized_attribute_settings_1: |-
+  client.index("INDEX_NAME").resetLocalizedAttributesSettings();

src/main/java/com/meilisearch/sdk/Index.java

@@ -697,6 +697,46 @@ public TaskInfo resetDisplayedAttributesSettings() throws MeilisearchException {
         return this.settingsHandler.resetDisplayedAttributesSettings(this.uid);
     }
 
+    /**
+     * Gets the localized attributes of the index
+     *
+     * @return localized attributes of a given uid as LocalizedAttribute
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/settings#get-localized-attributes">API
+     *     specification</a>
+     */
+    public LocalizedAttribute[] getLocalizedAttributesSettings() throws MeilisearchException {
+        return this.settingsHandler.getLocalizedAttributes(this.uid);
+    }
+
+    /**
+     * Updates the localized attributes of the index
+     *
+     * @param localizedAttributes An array of localized attributes that contains attributes of an
+     *     index to display
+     * @return TaskInfo instance
+     * @throws MeilisearchException if an error occurs
+     * @see <a
+     *     href="https://www.meilisearch.com/docs/reference/api/settings#update-localized-attribute-settings">API
+     *     specification</a>
+     */
+    public TaskInfo updateLocalizedAttributesSettings(LocalizedAttribute[] localizedAttributes)
+            throws MeilisearchException {
+        return this.settingsHandler.updateLocalizedAttributesSettings(
+                this.uid, localizedAttributes);
+    }
+
+    /**
+     * Resets the localized attributes of the index
+     *
+     * @return TaskInfo instance
+     * @throws MeilisearchException if an error occurs
+     */
+    public TaskInfo resetLocalizedAttributesSettings() throws MeilisearchException {
+        return this.settingsHandler.resetLocalizedAttributesSettings(this.uid);
+    }
+
     /**
      * Gets the filterable attributes of the index
      *

src/main/java/com/meilisearch/sdk/IndexSearchRequest.java

@@ -36,6 +36,7 @@ public class IndexSearchRequest {
     protected Double rankingScoreThreshold;
     private String[] attributesToSearchOn;
     private FederationOptions federationOptions;
+    protected String[] locales;
     protected String distinct;
 
     /**
@@ -104,6 +105,7 @@ public String toString() {
                         .putOpt("showRankingScoreDetails", this.showRankingScoreDetails)
                         .putOpt("rankingScoreThreshold", this.rankingScoreThreshold)
                         .putOpt("attributesToSearchOn", this.attributesToSearchOn)
+                        .putOpt("locales", this.locales)
                         .putOpt("distinct", this.distinct);
 
         return jsonObject.toString();

src/main/java/com/meilisearch/sdk/SearchRequest.java

@@ -40,6 +40,7 @@ public class SearchRequest {
     protected Boolean showRankingScore;
     protected Boolean showRankingScoreDetails;
     protected Double rankingScoreThreshold;
+    protected String[] locales;
     protected String distinct;
 
     /**
@@ -102,6 +103,7 @@ public String toString() {
                         .putOpt("showRankingScore", this.showRankingScore)
                         .putOpt("showRankingScoreDetails", this.showRankingScoreDetails)
                         .putOpt("rankingScoreThreshold", this.rankingScoreThreshold)
+                        .putOpt("locales", this.locales)
                         .putOpt("distinct", this.distinct);
 
         return jsonObject.toString();

src/main/java/com/meilisearch/sdk/SettingsHandler.java

@@ -3,6 +3,7 @@
 import com.meilisearch.sdk.exceptions.MeilisearchException;
 import com.meilisearch.sdk.http.URLBuilder;
 import com.meilisearch.sdk.model.Faceting;
+import com.meilisearch.sdk.model.LocalizedAttribute;
 import com.meilisearch.sdk.model.Pagination;
 import com.meilisearch.sdk.model.Settings;
 import com.meilisearch.sdk.model.TaskInfo;
@@ -266,6 +267,50 @@ TaskInfo resetDisplayedAttributesSettings(String uid) throws MeilisearchExceptio
                 settingsPath(uid).addSubroute("displayed-attributes").getURL(), TaskInfo.class);
     }
 
+    /**
+     * Gets the localized attributes of the index
+     *
+     * @param uid Index identifier
+     * @return an array of localizedattributes that contains attributes of the index to display
+     * @throws MeilisearchException if an error occurs
+     */
+    LocalizedAttribute[] getLocalizedAttributes(String uid) throws MeilisearchException {
+        return httpClient.get(
+                settingsPath(uid).addSubroute("localized-attributes").getURL(),
+                LocalizedAttribute[].class);
+    }
+
+    /**
+     * Updates the localized attributes of the index.
+     *
+     * @param uid Index identifier
+     * @param localizedAttributes an array of LocalizedAttributes that contain patterns and locales
+     *     settings
+     * @return TaskInfo instance
+     * @throws MeilisearchException if an error occurs
+     */
+    TaskInfo updateLocalizedAttributesSettings(String uid, LocalizedAttribute[] localizedAttributes)
+            throws MeilisearchException {
+        return httpClient.put(
+                settingsPath(uid).addSubroute("localized-attributes").getURL(),
+                localizedAttributes == null
+                        ? httpClient.jsonHandler.encode(localizedAttributes)
+                        : localizedAttributes,
+                TaskInfo.class);
+    }
+
+    /**
+     * Resets the localized attributes of the index
+     *
+     * @param uid Index identifier
+     * @return TaskInfo instance
+     * @throws MeilisearchException if an error occurs
+     */
+    TaskInfo resetLocalizedAttributesSettings(String uid) throws MeilisearchException {
+        return httpClient.delete(
+                settingsPath(uid).addSubroute("localized-attributes").getURL(), TaskInfo.class);
+    }
+
     /**
      * Gets the filterableAttributes of the index
      *

src/main/java/com/meilisearch/sdk/model/LocalizedAttribute.java

@@ -0,0 +1,21 @@
+package com.meilisearch.sdk.model;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+/**
+ * LocalizedAttribute setting data structure
+ *
+ * @see <a href="https://www.meilisearch.com/docs/reference/api/settings#localized-attributes">API
+ *     specification</a>
+ */
+@Getter
+@Setter
+@AllArgsConstructor
+@NoArgsConstructor
+public class LocalizedAttribute {
+    protected String[] attributePatterns;
+    protected String[] locales;
+}

src/main/java/com/meilisearch/sdk/model/Settings.java

@@ -32,6 +32,7 @@ public class Settings {
     protected String[] separatorTokens;
     protected String[] nonSeparatorTokens;
     protected HashMap<String, Embedders> embedders;
+    protected LocalizedAttribute[] localizedAttributes;
 
     public Settings() {}
 }

src/test/java/com/meilisearch/integration/SearchTest.java

@@ -1119,4 +1119,80 @@ public void testSimilarDocuments() throws Exception {
         assertThat(hits.get(2).get("title"), is("How to Train Your Dragon: The Hidden World"));
         assertThat(hits.get(3).get("title"), is("Shazam!"));
     }
+
+    /** Test Search with locales */
+    @Test
+    public void testSearchWithLocales() throws Exception {
+        String indexUid = "SearchLocales";
+        Index index = client.index(indexUid);
+        GsonJsonHandler jsonGson = new GsonJsonHandler();
+
+        TestData<Movie> testData = this.getTestData(NESTED_MOVIES, Movie.class);
+        TaskInfo task = index.addDocuments(testData.getRaw());
+
+        index.waitForTask(task.getTaskUid());
+
+        Settings settings = index.getSettings();
+
+        LocalizedAttribute localizedAttribute = new LocalizedAttribute();
+        localizedAttribute.setAttributePatterns(new String[] {"title", "comment"});
+        localizedAttribute.setLocales(new String[] {"fra", "eng"});
+        settings.setLocalizedAttributes(new LocalizedAttribute[] {localizedAttribute});
+
+        index.waitForTask(index.updateSettings(settings).getTaskUid());
+
+        SearchRequest searchRequest =
+                SearchRequest.builder().q("french").locales(new String[] {"fra", "eng"}).build();
+
+        Results resGson = jsonGson.decode(index.rawSearch(searchRequest), Results.class);
+
+        assertThat(resGson.hits, is(arrayWithSize(2)));
+    }
+
+    /** Test multisearch with locales */
+    @Test
+    public void testMultiSearchWithLocales() throws Exception {
+        HashSet<String> indexUids = new HashSet<String>();
+        indexUids.add("LocaleSearch1");
+        indexUids.add("LocaleSearch2");
+
+        for (String indexUid : indexUids) {
+            Index index = client.index(indexUid);
+
+            TestData<Movie> testData = this.getTestData(NESTED_MOVIES, Movie.class);
+            TaskInfo task = index.addDocuments(testData.getRaw());
+
+            index.waitForTask(task.getTaskUid());
+
+            Settings settings = index.getSettings();
+
+            LocalizedAttribute localizedAttribute = new LocalizedAttribute();
+            localizedAttribute.setAttributePatterns(new String[] {"title", "comment"});
+            localizedAttribute.setLocales(new String[] {"fra", "eng"});
+            settings.setLocalizedAttributes(new LocalizedAttribute[] {localizedAttribute});
+
+            index.waitForTask(index.updateSettings(settings).getTaskUid());
+        }
+
+        MultiSearchRequest search = new MultiSearchRequest();
+
+        search.addQuery(
+                new IndexSearchRequest("LocaleSearch1")
+                        .setQuery("")
+                        .setLocales(new String[] {"eng"}));
+        search.addQuery(
+                new IndexSearchRequest("LocaleSearch2")
+                        .setQuery("french")
+                        .setLocales(new String[] {"fra"}));
+
+        MultiSearchResult[] results = client.multiSearch(search).getResults();
+
+        assertThat(results.length, is(2));
+
+        for (MultiSearchResult searchResult : results) {
+            assertThat(indexUids.contains(searchResult.getIndexUid()), is(true));
+        }
+        assertThat(results[0].getHits().size(), is(7));
+        assertThat(results[1].getHits().size(), is(2));
+    }
 }