feat: add files template option (#882)

Author: stepan662

tolgee-cli/project-configuration.mdx

@@ -14,10 +14,8 @@ Example configuration:
   "format": "JSON_TOLGEE",
   "patterns": ["./src/**/*.ts?(x)"],
   "push": {
-    "files": [{
-      "path": "./public/i18n/en.json",
-      "language": "en"
-    }],
+    "filesTemplate": "./public/i18n/{languageTag}.json",
+    "language": ["en"],
     "forceMode": "OVERRIDE",
   },
   "pull": {
@@ -92,7 +90,7 @@ file.
 
 ### `patterns`
 
-List&ltString&gt. File glob patterns to your source code, used for key extraction.
+List[String]. File glob patterns to your source code, used for key extraction.
 
 ### `strictNamespace`
 
@@ -104,24 +102,40 @@ String. Default namespace used in extraction if not specified otherwise.
 
 ### `parser`
 
-Enum&lt`react`|`vue`|`svelte`&gt. Tolgee detects which parser to use automatically from the extensions of matched files, with this option you can override it.
+Enum[`react`|`vue`|`svelte`]. Tolgee detects which parser to use automatically from the extensions of matched files, with this option you can override it.
 
 
 ## Push options
 
 Related to `push` command, which imports the keys into the platform.
 
+### `push.filesTemplate`
+
+String or String[]. A template that describes the structure of the local files and their location.
+
+Example: `./public/{namespace}/{languageTag}.json`
+
+Full syntax is explained [here](./push-pull-strings.mdx#file-structure-template-format)
+
 ### `push.files`
 
+More explicit alternative to `filesTemplate`.
+
 `List<{path: string, language: string, namespace?: string}>`. Define, which files should be pushed and attach language/namespace to them. By default Tolgee pushes all files specified here, you can filter them by `languages` and `namespaces` properties. Path can be a glob, if you want to include multiple files.
 
+:::info `push.filesTemplate` vs `push.files`
+We recommend usage of [`push.filesTemplate`](#pushfilestemplate), which can describe your local localization file structure
+with single option. `push.files` requires you to specify each pushed file individually, but can be useful, if you have a weird file
+structure or you want to remap language tags.
+:::
+
 ### `push.languages`
 
-List&ltString&gt. Specifies which languages should be pushed from `push.files`.
+List[String]. Specifies which languages should be pushed from `push.files`.
 
 ### `push.namespaces`
 
-List&ltString&gt. Specifies which namespaces should be pushed from `push.files`.
+List[String]. Specifies which namespaces should be pushed from `push.files`.
 
 ### `push.forceMode`
 
@@ -142,7 +156,7 @@ Boolean. Convert placeholders in local files to ICU format. (Default: `true`)
 
 ### `push.tagNewKeys`
 
-List&ltString&gt. Specify tags that will be added to newly created keys.
+List[String]. Specify tags that will be added to newly created keys.
 
 ### `push.removeOtherKeys`
 
@@ -165,23 +179,23 @@ behavior by specifying `null` or empty string `""`.
 
 ### `pull.languages`
 
-List&ltString&gt. List of languages to pull. Leave unspecified to export them all.
+List[String]. List of languages to pull. Leave unspecified to export them all.
 
 ### `pull.namespaces`
 
-List&ltString&gt. List of namespaces to pull. Defaults to all namespaces.
+List[String]. List of namespaces to pull. Defaults to all namespaces.
 
 ### `pull.states`
 
-List&ltString&gt. List of translation states to include. Defaults all except untranslated.
+List[String]. List of translation states to include. Defaults all except untranslated.
 
 ### `pull.tags`
 
-List&ltString&gt. List of tags which to include.
+List[String]. List of tags which to include.
 
 ### `pull.excludeTags`
 
-List&ltString&gt. List of tags which to exclude.
+List[String]. List of tags which to exclude.
 
 ### `pull.supportArrays`
 
@@ -191,13 +205,9 @@ Boolean. Export keys with array syntax (e.g. `item[0]`) as arrays.
 
 String. This is a template that defines the structure of the resulting .zip file content.
 
-The template is a string that can contain the following placeholders: `{namespace}`, `{languageTag}`, `{androidLanguageTag}`, `{snakeLanguageTag}`, `{extension}`.
-
-For example, when exporting to JSON with the template `{namespace}/{languageTag}.{extension}`, the English translations of the home namespace will be stored in home/en.json.
-
-The `{snakeLanguageTag}` placeholder is the same as `{languageTag}` but in snake case. (e.g., en_US).
+Example: `{namespace}/{languageTag}.{extension}`
 
-The Android specific `{androidLanguageTag}` placeholder is the same as `{languageTag}` but in Android format. (e.g., en-rUS)
+Full syntax is explained [here](./push-pull-strings.mdx#file-structure-template-format)
 
 ### `pull.emptyDir`
 
@@ -229,24 +239,24 @@ Boolean. Extract keys from code and filter them out.
 
 ### `tag.filterTag`
 
-List&ltString&gt. Filter only keys with tag. Use * as a wildcard.
+List[String]. Filter only keys with tag. Use * as a wildcard.
 
 ### `tag.filterNoTag`
 
-List&ltString&gt. Filter only keys without tag. Use * as a wildcard.
+List[String]. Filter only keys without tag. Use * as a wildcard.
 
 ### `tag.tag`
 
-List&ltString&gt. Add tag to filtered keys.
+List[String]. Add tag to filtered keys.
 
 ### `tag.tagOther`
 
-List&ltString&gt. Tag keys which are not filtered.
+List[String]. Tag keys which are not filtered.
 
 ### `tag.untag`
 
-List&ltString&gt. Remove tag from filtered keys. Use * as a wildcard.
+List[String]. Remove tag from filtered keys. Use * as a wildcard.
 
 ### `tag.untagOther`
 
-List&ltString&gt. Remove tag from keys which are not filtered. Use * as a wildcard.
+List[String]. Remove tag from keys which are not filtered. Use * as a wildcard.

tolgee-cli/push-pull-strings.mdx

@@ -31,18 +31,7 @@ Options:
 - `--exclude-tags <tags...>` - List of tags which to exclude. Keys tagged by at least one of these tags will be excluded.
 - `--support-arrays` - Export keys with array syntax (e.g. item[0]) as arrays. (default: false)
 - `--empty-dir` - Empty target directory before inserting pulled files.
-- `--file-structure-template <template>` - [Defines exported file structure](#file-structure-template-format)
-
-### File structure template format
-This is a template that defines the structure of the resulting .zip file content.
-
-The template is a string that can contain the following placeholders: `{namespace}`, `{languageTag}`, `{androidLanguageTag}`, `{snakeLanguageTag}`, `{extension}`.
-
-For example, when exporting to JSON with the template `{namespace}`/`{languageTag}`.`{extension}`, the English translations of the home namespace will be stored in home/en.json.
-
-The `{snakeLanguageTag}` placeholder is the same as `{languageTag}` but in snake case. (e.g., en_US).
-
-The Android specific `{androidLanguageTag}` placeholder is the same as `{languageTag}` but in Android format. (e.g., en-rUS)
+- `--file-structure-template <template>` - [Defines exported file structure](#file-structure-template-format).
 
 ## Pushing strings
 
@@ -55,16 +44,26 @@ Example usage:
    tolgee push --force-mode OVERRIDE
 ```
 
-:::info
-Push command requires [`push.files`](./project-configuration.mdx#pushfiles) in config (which specifies which files to import).
-:::
-
 Options:
-
+- `--files-template <templates...>` (short: `-ft`) - A template that describes the structure of the local files and their location with [file structure template format](#file-structure-template-format). Example: `./public/{namespace}/{languageTag}.json`
 - `--force-mode <mode>` (short: `-f`) – What should we do with possible conflicts? Available modes: `OVERRIDE`, `KEEP`, `NO_FORCE` (abort on conflicts). Defaults to asking the user interactively (or `NO_FORCE` if it is not possible).
 - `--override-key-descriptions` - Override existing key descriptions from local files (only relevant for some formats).
 - `--convert-placeholders-to-icu` - Convert placeholders in local files to ICU format. (Default: true)
 - `--languages <languages...>` (short `-l`) - Specifies which languages should be pushed (see `push.files` in config).
 - `--namespaces <namespaces...>` (short `-n`) - Specifies which namespaces should be pushed (see `push.files` in config).
 - `--tag-new-keys <tags...>` - Specify tags that will be added to newly created keys.
 - `--remove-other-keys` - Remove keys which are not present in the import.
+
+
+### File structure template format
+This is a template that defines the structure of static files and mapping them to languages/namespaces.
+
+The template is a string that can contain the following placeholders: `{namespace}`, `{languageTag}`, `{androidLanguageTag}`, `{snakeLanguageTag}`, `{extension}`.
+
+For example, when exporting to JSON with the template `{namespace}`/`{languageTag}`.`{extension}`, the English translations of the home namespace will be stored in home/en.json.
+
+The `{snakeLanguageTag}` placeholder is the same as `{languageTag}` but in snake case. (e.g., en_US).
+
+The Android specific `{androidLanguageTag}` placeholder is the same as `{languageTag}` but in Android format. (e.g., en-rUS)
+
+> `--files-template` option also allows usage of glob wildcards as (`*`, `**` or `{json,yaml}`)