Merge pull request #197 from ckeditor/ci/3817

Other: The generated package no longer integrates with the Transifex service. Thanks to that, a community can provide translation entries directly via pull requests.

MAJOR BREAKING CHANGE (generator): Removed the `translations:collect`, `translations:download` and `translations:upload` scripts from the generated package. Instead, the `translations:synchronize` and `translations:validate` scripts are introduced. These two new scripts do not provide an integration with Transifex service anymore, but they help preparing translation files (`*.po` files) which must be handled by the integrator himself.

MAJOR BREAKING CHANGE (tools): Removed the `translations:collect`, `translations:download` and `translations:upload` tasks. Instead, the `translations:synchronize` task is introduced. It helps preparing translation files (`*.po` files) in the generated package.

package.json

@@ -18,10 +18,10 @@
   "homepage": "https://ckeditor.com/ckeditor-5",
   "type": "module",
   "devDependencies": {
-    "@ckeditor/ckeditor5-dev-bump-year": "^44.0.0",
-    "@ckeditor/ckeditor5-dev-ci": "^44.0.0",
-    "@ckeditor/ckeditor5-dev-release-tools": "^44.0.0",
-    "@ckeditor/ckeditor5-dev-web-crawler": "^44.0.0",
+    "@ckeditor/ckeditor5-dev-bump-year": "^45.0.0",
+    "@ckeditor/ckeditor5-dev-ci": "^45.0.0",
+    "@ckeditor/ckeditor5-dev-release-tools": "^45.0.0",
+    "@ckeditor/ckeditor5-dev-web-crawler": "^45.0.0",
     "@vitest/coverage-v8": "^2.1.1",
     "chalk": "^5.0.0",
     "coveralls": "^3.1.1",

packages/ckeditor5-package-generator/lib/templates/js-legacy/README.md

@@ -14,9 +14,8 @@ This package was created by the [ckeditor5-package-generator](https://www.npmjs.
   * [`build:dist`](#builddist)
   * [`dll:build`](#dllbuild)
   * [`dll:serve`](#dllserve)
-  * [`translations:collect`](#translationscollect)
-  * [`translations:download`](#translationsdownload)
-  * [`translations:upload`](#translationsupload)
+  * [`translations:synchronize`](#translationssynchronize)
+  * [`translations:validate`](#translationsvalidate)
 * [License](#license)
 
 ## Developing the package
@@ -124,48 +123,37 @@ Examples:
 <%= packageManager %> run dll:serve
 ```
 
-### `translations:collect`
+### `translations:synchronize`
 
-Collects translation messages (arguments of the `t()` function) and context files, then validates whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+Synchronizes translation messages (arguments of the `t()` function) by performing the following steps:
+
+ * Collect all translation messages from the package by finding `t()` calls in source files.
+ * Detect if translation context is valid, i.e. whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+ * If there are no validation errors, update all translation files (`*.po` files) to be in sync with the context file:
+   * unused translation entries are removed,
+   * missing translation entries are added with empty string as the message translation,
+   * missing translation files are created for languages that do not have own `*.po` file yet.
 
 The task may end with an error if one of the following conditions is met:
 
 * Found the `Unused context` error &ndash; entries specified in the `lang/contexts.json` file are not used in source files. They should be removed.
-* Found the `Context is duplicated for the id` error &ndash; some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewrite them.
-* Found the `Context for the message id is missing` error &ndash; entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
-
-Examples:
-
-```bash
-<%= packageManager %> run translations:collect
-```
-
-### `translations:download`
-
-Download translations from the Transifex server. Depending on users' activity in the project, it creates translation files used for building the editor.
-
-The task requires passing the URL to Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
-
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:download` command.
+* Found the `Duplicated contex` error &ndash; some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewriting them.
+* Found the `Missing context` error &ndash; entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:download <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:synchronize
 ```
 
-### `translations:upload`
-
-Uploads translation messages onto the Transifex server. It allows users to create translations into other languages using the Transifex platform.
-
-The task requires passing the URL to the Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
+### `translations:validate`
 
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:upload` command.
+Peforms only validation steps as described in [`translations:synchronize`](#translationssynchronize) script, but without modifying any files. It only checks the correctness of the context file against the `t()` function calls.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:upload <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:validate
 ```
 
 ## License

packages/ckeditor5-package-generator/lib/templates/js-legacy/package.json

@@ -66,9 +66,8 @@
     "test": "vitest",
     "test:debug": "vitest --inspect-brk --no-file-parallelism --browser.headless=false",
     "prepare": "<%= packageManager %> run dll:build && <%= packageManager %> run build:dist",
-    "translations:collect": "ckeditor5-package-tools translations:collect",
-    "translations:download": "ckeditor5-package-tools translations:download",
-    "translations:upload": "ckeditor5-package-tools translations:upload"
+    "translations:synchronize": "ckeditor5-package-tools translations:synchronize",
+    "translations:validate": "ckeditor5-package-tools translations:synchronize --validate-only"
   },
   "lint-staged": {
     "**/*.js": [

packages/ckeditor5-package-generator/lib/templates/js/README.md

@@ -12,9 +12,8 @@ This package was created by the [ckeditor5-package-generator](https://www.npmjs.
   * [`lint`](#lint)
   * [`stylelint`](#stylelint)
   * [`build:dist`](#builddist)
-  * [`translations:collect`](#translationscollect)
-  * [`translations:download`](#translationsdownload)
-  * [`translations:upload`](#translationsupload)
+  * [`translations:synchronize`](#translationssynchronize)
+  * [`translations:validate`](#translationsvalidate)
 * [License](#license)
 
 ## Developing the package
@@ -96,48 +95,37 @@ Examples:
 npm run build:dist
 ```
 
-### `translations:collect`
+### `translations:synchronize`
 
-Collects translation messages (arguments of the `t()` function) and context files, then validates whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+Synchronizes translation messages (arguments of the `t()` function) by performing the following steps:
+
+ * Collect all translation messages from the package by finding `t()` calls in source files.
+ * Detect if translation context is valid, i.e. whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+ * If there are no validation errors, update all translation files (`*.po` files) to be in sync with the context file:
+   * unused translation entries are removed,
+   * missing translation entries are added with empty string as the message translation,
+   * missing translation files are created for languages that do not have own `*.po` file yet.
 
 The task may end with an error if one of the following conditions is met:
 
 * Found the `Unused context` error – entries specified in the `lang/contexts.json` file are not used in source files. They should be removed.
-* Found the `Context is duplicated for the id` error – some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewriting them.
-* Found the `Context for the message id is missing` error – entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
-
-Examples:
-
-```bash
-<%= packageManager %> run translations:collect
-```
-
-### `translations:download`
-
-Download translations from the Transifex server. Depending on users' activity in the project, it creates translation files used for building the editor.
-
-The task requires passing the URL to Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
-
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:download` command.
+* Found the `Duplicated contex` error &ndash; some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewriting them.
+* Found the `Missing context` error &ndash; entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:download <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:synchronize
 ```
 
-### `translations:upload`
-
-Uploads translation messages onto the Transifex server. It allows users to create translations into other languages using the Transifex platform.
-
-The task requires passing the URL to the Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
+### `translations:validate`
 
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:upload` command.
+Peforms only validation steps as described in [`translations:synchronize`](#translationssynchronize) script, but without modifying any files. It only checks the correctness of the context file against the `t()` function calls.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:upload <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:validate
 ```
 
 ## License

packages/ckeditor5-package-generator/lib/templates/js/package.json

@@ -57,9 +57,8 @@
     "test": "vitest",
     "test:debug": "vitest --inspect-brk --no-file-parallelism --browser.headless=false",
     "prepare": "<%= packageManager %> run build:dist",
-    "translations:collect": "ckeditor5-package-tools translations:collect",
-    "translations:download": "ckeditor5-package-tools translations:download",
-    "translations:upload": "ckeditor5-package-tools translations:upload"
+    "translations:synchronize": "ckeditor5-package-tools translations:synchronize",
+    "translations:validate": "ckeditor5-package-tools translations:synchronize --validate-only"
   },
   "lint-staged": {
     "**/*.js": [

packages/ckeditor5-package-generator/lib/templates/ts-legacy/README.md

@@ -14,9 +14,8 @@ This package was created by the [ckeditor5-package-generator](https://www.npmjs.
   * [`build:dist`](#builddist)
   * [`dll:build`](#dllbuild)
   * [`dll:serve`](#dllserve)
-  * [`translations:collect`](#translationscollect)
-  * [`translations:download`](#translationsdownload)
-  * [`translations:upload`](#translationsupload)
+  * [`translations:synchronize`](#translationssynchronize)
+  * [`translations:validate`](#translationsvalidate)
   * [`ts:build` and `ts:clear`](#tsbuild-and-tsclear)
 * [License](#license)
 
@@ -125,48 +124,37 @@ Examples:
 <%= packageManager %> run dll:serve
 ```
 
-### `translations:collect`
+### `translations:synchronize`
 
-Collects translation messages (arguments of the `t()` function) and context files, then validates whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+Synchronizes translation messages (arguments of the `t()` function) by performing the following steps:
+
+ * Collect all translation messages from the package by finding `t()` calls in source files.
+ * Detect if translation context is valid, i.e. whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+ * If there are no validation errors, update all translation files (`*.po` files) to be in sync with the context file:
+   * unused translation entries are removed,
+   * missing translation entries are added with empty string as the message translation,
+   * missing translation files are created for languages that do not have own `*.po` file yet.
 
 The task may end with an error if one of the following conditions is met:
 
 * Found the `Unused context` error &ndash; entries specified in the `lang/contexts.json` file are not used in source files. They should be removed.
-* Found the `Context is duplicated for the id` error &ndash; some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewrite them.
-* Found the `Context for the message id is missing` error &ndash; entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
-
-Examples:
-
-```bash
-<%= packageManager %> run translations:collect
-```
-
-### `translations:download`
-
-Download translations from the Transifex server. Depending on users' activity in the project, it creates translation files used for building the editor.
-
-The task requires passing the URL to Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
-
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:download` command.
+* Found the `Duplicated contex` error &ndash; some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewriting them.
+* Found the `Missing context` error &ndash; entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:download <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:synchronize
 ```
 
-### `translations:upload`
-
-Uploads translation messages onto the Transifex server. It allows users to create translations into other languages using the Transifex platform.
-
-The task requires passing the URL to the Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
+### `translations:validate`
 
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:upload` command.
+Peforms only validation steps as described in [`translations:synchronize`](#translationssynchronize) script, but without modifying any files. It only checks the correctness of the context file against the `t()` function calls.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:upload <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:validate
 ```
 
 ### `ts:build` and `ts:clear`

packages/ckeditor5-package-generator/lib/templates/ts-legacy/package.json

@@ -81,9 +81,8 @@
     "prepare": "<%= packageManager %> run dll:build && <%= packageManager %> run build:dist",
     "prepublishOnly": "<%= packageManager %> run ts:build && ckeditor5-package-tools export-package-as-javascript",
     "postpublish": "<%= packageManager %> run ts:clear && ckeditor5-package-tools export-package-as-typescript",
-    "translations:collect": "ckeditor5-package-tools translations:collect",
-    "translations:download": "ckeditor5-package-tools translations:download",
-    "translations:upload": "ckeditor5-package-tools translations:upload"
+    "translations:synchronize": "ckeditor5-package-tools translations:synchronize",
+    "translations:validate": "ckeditor5-package-tools translations:synchronize --validate-only"
   },
   "lint-staged": {
     "**/*.{js,ts}": [

packages/ckeditor5-package-generator/lib/templates/ts/README.md

@@ -12,9 +12,8 @@ This package was created by the [ckeditor5-package-generator](https://www.npmjs.
   * [`lint`](#lint)
   * [`stylelint`](#stylelint)
   * [`build:dist`](#builddist)
-  * [`translations:collect`](#translationscollect)
-  * [`translations:download`](#translationsdownload)
-  * [`translations:upload`](#translationsupload)
+  * [`translations:synchronize`](#translationssynchronize)
+  * [`translations:validate`](#translationsvalidate)
   * [`ts:build` and `ts:clear`](#tsbuild-and-tsclear)
 * [License](#license)
 
@@ -98,48 +97,37 @@ Examples:
 npm run build:dist
 ```
 
-### `translations:collect`
+### `translations:synchronize`
 
-Collects translation messages (arguments of the `t()` function) and context files, then validates whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+Synchronizes translation messages (arguments of the `t()` function) by performing the following steps:
+
+ * Collect all translation messages from the package by finding `t()` calls in source files.
+ * Detect if translation context is valid, i.e. whether the provided values do not interfere with the values specified in the `@ckeditor/ckeditor5-core` package.
+ * If there are no validation errors, update all translation files (`*.po` files) to be in sync with the context file:
+   * unused translation entries are removed,
+   * missing translation entries are added with empty string as the message translation,
+   * missing translation files are created for languages that do not have own `*.po` file yet.
 
 The task may end with an error if one of the following conditions is met:
 
 * Found the `Unused context` error – entries specified in the `lang/contexts.json` file are not used in source files. They should be removed.
-* Found the `Context is duplicated for the id` error – some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewrite them.
-* Found the `Context for the message id is missing` error – entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
-
-Examples:
-
-```bash
-<%= packageManager %> run translations:collect
-```
-
-### `translations:download`
-
-Download translations from the Transifex server. Depending on users' activity in the project, it creates translation files used for building the editor.
-
-The task requires passing the URL to Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
-
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:download` command.
+* Found the `Duplicated contex` error &ndash; some of the entries are duplicated. Consider removing them from the `lang/contexts.json` file, or rewriting them.
+* Found the `Missing context` error &ndash; entries specified in source files are not described in the `lang/contexts.json` file. They should be added.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:download <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:synchronize
 ```
 
-### `translations:upload`
-
-Uploads translation messages onto the Transifex server. It allows users to create translations into other languages using the Transifex platform.
-
-The task requires passing the URL to the Transifex API. Usually, it matches the following format: `https://www.transifex.com/api/2/project/[PROJECT_SLUG]`.
+### `translations:validate`
 
-To avoid passing the `--transifex` option whenever you call the command, you can store it in `package.json`, next to the `ckeditor5-package-tools translations:upload` command.
+Peforms only validation steps as described in [`translations:synchronize`](#translationssynchronize) script, but without modifying any files. It only checks the correctness of the context file against the `t()` function calls.
 
 Examples:
 
 ```bash
-<%= packageManager %> run translations:upload <%= cliSeparator %>--transifex [API URL]
+<%= packageManager %> run translations:validate
 ```
 
 ### `ts:build` and `ts:clear`

packages/ckeditor5-package-generator/lib/templates/ts/package.json

@@ -69,9 +69,8 @@
     "prepare": "<%= packageManager %> run build:dist",
     "prepublishOnly": "<%= packageManager %> run ts:build && ckeditor5-package-tools export-package-as-javascript",
     "postpublish": "<%= packageManager %> run ts:clear && ckeditor5-package-tools export-package-as-typescript",
-    "translations:collect": "ckeditor5-package-tools translations:collect",
-    "translations:download": "ckeditor5-package-tools translations:download",
-    "translations:upload": "ckeditor5-package-tools translations:upload"
+    "translations:synchronize": "ckeditor5-package-tools translations:synchronize",
+    "translations:validate": "ckeditor5-package-tools translations:synchronize --validate-only"
   },
   "lint-staged": {
     "**/*.{js,ts}": [