diff --git a/website/docs/tutorials/files-management.md b/website/docs/tutorials/files-management.md new file mode 100644 index 00000000..294e8d8f --- /dev/null +++ b/website/docs/tutorials/files-management.md @@ -0,0 +1,186 @@ +--- +description: Learn how to manage your project's localization files from the command line. Synchronize your source language files and translations with your Crowdin project. +--- + +# Files management + +## Introduction + +Crowdin CLI allows you to manage your project's localization files from the command line. You can easily synchronize your source language files and translations with your Crowdin project. + +There are several commands you can use to manage your files. The CLI provides high-level commands that are easy to use and low-level commands that give you more flexibility and control. + +The high level commands are [`crowdin upload`](/commands/crowdin-upload) and [`crowdin download`](/commands/crowdin-download). These commands are easy to use and they rely mostly on the configuration file. + +The low-level commands include [`crowdin file upload`](/commands/crowdin-file-upload), [`crowdin file download`](/commands/crowdin-file-download), and [`crowdin file delete`](/commands/crowdin-file-delete). These commands are more like a lightweight wrapper over the [Crowdin API](https://developer.crowdin.com/api/v2/). They give you more flexibility and control over the file management process. These commands are also supported by string-based projects. + +## The `upload` and `download` commands + +### Configuration + +These commands are usually being used along with the configuration file. + +For example, you have a project with the following structure: + +```bash +. +├── locales +│ ├── en +│ │ └── messages.xml +│ └── fr +│ │ └── messages.xml +│ └── de +│ │ └── messages.xml +│ └── uk +│ └── messages.xml +└── ... +``` + +Let's create a simple configuration file: + +```bash +crowdin init -s "locales/en/*.xml" -t "locales/%two_letters_code%/%original_file_name%" +``` + +This command prompts you for the project identifier and API token. It will then create a configuration file with the following content: + +```yaml +"project_id": "" +"api_token": "" +"base_path": "." +"base_url": "https://api.crowdin.com" + +"preserve_hierarchy": true + +files: [ + { + "source": "locales/en/*.xml", + "translation": "locales/%two_letters_code%/%original_file_name%" + } +] +``` + +Let's take a closer look at some of the configuration options. + +The `source` and `translation` configurations represent the patterns for the source and translation files. The `source` configuration is a [glob](https://en.wikipedia.org/wiki/Glob_(programming)) pattern pointing to the source files. The `translation` configuration is a path to the translation files (existing ones or where to put downloaded translations). The `%two_letters_code%` and `%original_file_name%` are the placeholders that will be replaced by the language code and the original source file name, respectively. + +:::info +Visit the [Configuration](/configuration) page to learn more about the configuration file. +::: + +### Upload content + +Let's **upload** the source files and existing translations to Crowdin: + +```bash +crowdin upload sources +crowdin upload translations -l fr +``` + +We can also check the translation and proofreading progress before downloading the translations: + +```bash +crowdin status +``` + +### Download content + +When the translations are ready, we can **download** them: + +```bash +crowdin download translations +``` + +The above command will download all the translations to the path specified in the `translation` configuration. + +:::tip +You can also use short aliases: `crowdin push`, `crowdin pull`. +::: + +To download the source files from Crowdin, run the following command: + +```bash +crowdin download sources +``` + +:::caution +This way of managing files is not supported for string-based projects. Use the `files` command instead. +::: + +## The `file` command + +The [`file`](/commands/crowdin-file) command is a low-level command that allows you to manage your files with more flexibility and control. + +This command does not require a `files` section in the configuration file, or a configuration file at all. You can specify all the necessary parameters in the command itself. + +### Upload content + +Let's use the same project structure as in the previous example and try to **upload** the source files and existing translations to Crowdin: + +```bash +crowdin file upload locales/en/messages.xml -d messages.xml +``` + +The command above will take the file `locales/en/messages.xml` and upload it to Crowdin as `messages.xml` in the root directory. The `-d`/`--dest` option stands for `destination` and allows you to specify the path to the file in Crowdin. If you omit the `-d` option, the file will be uploaded to the root directory with the same path as the source file. + +You can also upload strings to string-based projects as well: + +```bash +crowdin file upload locales/en/messages.xml --branch main --cleanup-mode --update-strings +``` + +The `--branch` option is required for string-based projects. The `--cleanup-mode` and `--update-strings` options are not required. + +To **upload translations** you need to specify the `-l`/`--language` option: + +```bash +crowdin file upload locales/fr/messages.xml -d messages.xml -l fr +``` + +The `-d`/`--dest` option is the path to the file in Crowdin where the translations should be uploaded. `-l` - [Crowdin language code](https://developer.crowdin.com/language-codes/). + +Visit the [`crowdin file upload`](/commands/crowdin-file-upload) page to see all the options available. + +### Download content + +Using the `crowdin file download` you can download either the source files or translations. Let's try to download the source file from Crowdin: + +```bash +crowdin file download messages.xml -d locales/en/messages.xml +``` + +The above command will download the `messages.xml` file from Crowdin and store it in the `locales/en/messages.xml` path. + +To download translations, you need to specify the `-l`/`--language` option: + +```bash +crowdin file download messages.xml -d locales/fr -l fr +``` + +The `-d`/`--dest` option here is the path to the file on your local machine where the translations should be stored. `-l` - [Crowdin language code](https://developer.crowdin.com/language-codes/). + +:::info +You can also use language code placeholders in the `--dest` option. For example, `locales/%android_code%`. +Available codes: `%two_letters_code%`, `%three_letters_code%`, `%locale%`, `%android_code%`, `%osx_code%`, `%osx_locale%`. +::: + +Visit the [`crowdin file download`](/commands/crowdin-file-download) page to see all the available options. + +:::tip +The `file` commands can easily be used without the configuration file. For example: + +```bash +crowdin file upload locales/en/messages.xml \ + -d messages.xml \ + -i \ + -T \ + / +``` +::: + +## Further Reading + +- [Configuration](/configuration) +- [Advanced Usage](/advanced) +- [CI/CD Integration](/ci-cd) +- [FAQ](/faq) diff --git a/website/sidebars.js b/website/sidebars.js index d201c9ad..b0d5fe99 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -252,6 +252,15 @@ const sidebars = { 'commands/crowdin-pre-translate', ], }, + { + type: 'category', + label: 'Tutorials', + collapsible: true, + collapsed: false, + items: [ + 'tutorials/files-management', + ] + }, 'ci-cd', 'advanced', 'faq',