feat(API): add use_locale_fallback option to download #SCD-620 (#976)

Author: jablan

clients/java/src/test/java/com/phrase/client/api/LocalesApiTest.java

@@ -167,6 +167,7 @@ public void localeDownloadTest() throws ApiException, IOException, InterruptedEx
         Boolean includeUnverifiedTranslations = null;
         Boolean useLastReviewedVersion = null;
         String fallbackLocaleId = null;
+        Boolean useLocaleFallback = null;
         String sourceLocaleId = null;
         Object customMetadataFilters = null;
         String translationKeyPrefix = null;
@@ -177,7 +178,7 @@ public void localeDownloadTest() throws ApiException, IOException, InterruptedEx
             branch, fileFormat, tags, tag, includeEmptyTranslations, excludeEmptyZeroForms,
             includeTranslatedKeys, keepNotranslateTags, convertEmoji, formatOptions, encoding,
             skipUnverifiedTranslations, includeUnverifiedTranslations, useLastReviewedVersion,
-            fallbackLocaleId, sourceLocaleId, translationKeyPrefix, filterByPrefix,
+            fallbackLocaleId, useLocaleFallback, sourceLocaleId, translationKeyPrefix, filterByPrefix,
             customMetadataFilters, localeIds, updatedSince);
 
         String fileContents = new String(java.nio.file.Files.readAllBytes(response.toPath()));

doc/compiled.json

@@ -8833,13 +8833,22 @@
             }
           },
           {
-            "description": "If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to `true`.",
-            "example": null,
             "name": "fallback_locale_id",
+            "description": "If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.\nProvide the ID of the locale that should be used as the fallback.\nRequires `include_empty_translations` to be set to `true`. Mutually exclusive with `use_locale_fallback`.\n",
             "in": "query",
             "schema": {
               "type": "string"
-            }
+            },
+            "example": null
+          },
+          {
+            "name": "use_locale_fallback",
+            "description": "If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.\nFallback locale is defined in [locale's settings](/en/api/strings/locales/update-a-locale#body-fallback-locale-id).\nRequires `include_empty_translations` to be set to `true`. Mutually exclusive with `fallback_locale_id`.\n",
+            "in": "query",
+            "schema": {
+              "type": "boolean"
+            },
+            "example": true
           },
           {
             "description": "Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a `tag` parameter indicating a specific job.",
@@ -9053,10 +9062,15 @@
                     ]
                   },
                   "fallback_locale_id": {
-                    "description": "If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to `true`.",
+                    "description": "If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.\nProvide the ID of the locale that should be used as the fallback.\nRequires `include_empty_translations` to be set to `true`. Mutually exclusive with `use_locale_fallback`.\n",
                     "type": "string",
                     "example": "abcd1234abcd1234abcd1234abcd1234"
                   },
+                  "use_locale_fallback": {
+                    "description": "If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.\nFallback locale is defined in [locale's settings](/en/api/strings/locales/update-a-locale#body-fallback-locale-id).\nRequires `include_empty_translations` to be set to `true`. Mutually exclusive with `fallback_locale_id`.\n",
+                    "type": "boolean",
+                    "example": false
+                  },
                   "source_locale_id": {
                     "description": "Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a `tag` parameter indicating a specific job.",
                     "example": "abcd1234abcd1234abcd1234abcd1234",

paths/locale_downloads/create.yaml

@@ -73,9 +73,19 @@ requestBody:
               - de
               - en
           fallback_locale_id:
-            description: If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to `true`.
+            description: |
+              If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.
+              Provide the ID of the locale that should be used as the fallback.
+              Requires `include_empty_translations` to be set to `true`. Mutually exclusive with `use_locale_fallback`.
             type: string
             example: abcd1234abcd1234abcd1234abcd1234
+          use_locale_fallback:
+            description: |
+              If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.
+              Fallback locale is defined in [locale's settings](/en/api/strings/locales/update-a-locale#body-fallback-locale-id).
+              Requires `include_empty_translations` to be set to `true`. Mutually exclusive with `fallback_locale_id`.
+            type: boolean
+            example: false
           source_locale_id:
             description: Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a `tag` parameter indicating a specific job.
             example: abcd1234abcd1234abcd1234abcd1234

paths/locales/download.yaml

@@ -100,12 +100,24 @@ parameters:
     in: query
     schema:
       type: boolean
-  - description: If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to `true`.
-    example:
-    name: fallback_locale_id
+  - name: fallback_locale_id
+    description: |
+      If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.
+      Provide the ID of the locale that should be used as the fallback.
+      Requires `include_empty_translations` to be set to `true`. Mutually exclusive with `use_locale_fallback`.
     in: query
     schema:
       type: string
+    example:
+  - name: use_locale_fallback
+    description: |
+      If a key has no translation in the locale being downloaded, the translation in the fallback locale will be used.
+      Fallback locale is defined in [locale's settings](/en/api/strings/locales/update-a-locale#body-fallback-locale-id).
+      Requires `include_empty_translations` to be set to `true`. Mutually exclusive with `fallback_locale_id`.
+    in: query
+    schema:
+      type: boolean
+    example: true
   - description: Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a `tag` parameter indicating a specific job.
     example:
     name: source_locale_id