feat: add 'command' and 'command_args' options (#176)

- deprecate the _branch options_ in favor of the new _command options_ - add the `test-action.yml` GitHub workflow to test the Action - refine Readme - improve Examples - enforce conventional commits specification
crowdin · Jun 16, 2023 · ee4ab4e · ee4ab4e
1 parent 3133cc9
commit ee4ab4e
Show file tree

Hide file tree

Showing 8 changed files with 190 additions and 52 deletions.
diff --git a/.github/workflows/lint-pr-title.yml b/.github/workflows/lint-pr-title.yml
@@ -0,0 +1,18 @@
+name: lint-pr-title
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - edited
+      - synchronize
+
+jobs:
+  main:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/test-action.yml b/.github/workflows/test-action.yml
@@ -0,0 +1,26 @@
+name: 'test'
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - '*'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Crowdin Action
+        uses: ./
+        with:
+          command: 'push'
+          command_args: '-h'
+
+      - name: Get CLI version
+        uses: ./
+        with:
+          command: 'init'
+          command_args: '-V'
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.idea
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -63,7 +63,10 @@ Unsure where to begin contributing to Crowdin Action? You can start by looking t
 
 Before sending your pull requests, make sure you followed the list below:
 
-- Read this guidelines.
+- Read these guidelines.
 - Read [Code of Conduct](/CODE_OF_CONDUCT.md).
 - Ensure that your code adheres to standard conventions, as used in the rest of the project.
 - Ensure that your changes are well tested.
+
+> **Note**
+> This project uses the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages and PR titles.
diff --git a/EXAMPLES.md b/EXAMPLES.md
@@ -16,6 +16,9 @@
   - [When a new GitHub Release is published](#when-a-new-github-release-is-published)
   - [Dealing with concurrency](#dealing-with-concurrency)
   - [Handling parallel runs](#handling-parallel-runs)
+- [Tips and tricks](#tips-and-tricks)
+  - [Checking the translation progress](#checking-the-translation-progress)
+  - [Pre-Translation](#pre-translation)
 
 ---
 
@@ -106,18 +109,17 @@ jobs:
         with:
           upload_sources: true
           upload_translations: false
-
-          # Sources pattern
-          source: src/locale/en.json
-          # Translations pattern
-          translation: src/locale/%android_code%.json
-
-          project_id: ${{ secrets.CROWDIN_PROJECT_ID }}
-          token: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
+          source: src/locale/en.json                     # Sources pattern
+          translation: src/locale/%android_code%.json    # Translations pattern
+          project_id: ${{ secrets.CROWDIN_PROJECT_ID }}  # Crowdin Project ID
+          token: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}   # Crowdin Personal Access Token
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+> **Note**
+> To avoid any conflicts, do not use the `crowdin.yml` file in the repository when using the above configuration approach.
+
 ### Upload sources only
 
 ```yaml
@@ -167,16 +169,17 @@ jobs:
           upload_sources: true
           upload_translations: false
           download_translations: false
-          crowdin_branch_name: "${{ env.BRANCH_NAME }}"
+          crowdin_branch_name: ${{ env.BRANCH_NAME }}
         env:
           CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
           CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
 ```
 
+Note that the value of the `crowdin_branch_name` is `env.BRANCH_NAME` - this is the name of the current branch on which the action is running.
+
 ### Download only translations without pushing to a branch
 
-It's possible only to download the translations without immediate PR creation.
-It allows you to post-process the downloaded translations and create a PR later.
+It's possible to just download the translations without creating a PR immediately. It allows you to post-process the downloaded translations and create a PR later.
 
 ```yaml
 name: Crowdin Action
@@ -205,6 +208,8 @@ jobs:
           CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
 ```
 
+You can use the [Create Pull Request](https://github.com/marketplace/actions/create-pull-request) GitHub Action to create a PR with the downloaded translations.
+
 ### Advanced Pull Request configuration
 
 There is a possibility to specify labels, assignees, reviewers for PR created by the Action.
@@ -247,19 +252,22 @@ jobs:
 
 ### Custom `crowdin.yml` file location
 
+By default, the Action looks for the `crowdin.yml` file in the repository root. You can specify a custom location of the configuration file:
+
 ```yaml
-...
+# ...
 
 - name: Crowdin
   uses: crowdin/github-action@v1
   with:
     config: '.github/crowdin.yml'
-
-  ...
+    #...
 ```
 
 ### Separate PRs for each target language
 
+You can use the [`matrix`](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs) feature of GitHub Actions to create separate PRs for each target language:
+
 ```yaml
 name: Crowdin Action
 
@@ -296,7 +304,6 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
           CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
-
 ```
 
 ## Triggers
@@ -356,3 +363,60 @@ strategy:
 ```
 
 [Read more](https://github.com/crowdin/github-action/wiki/Handling-parallel-runs)
+
+## Tips and Tricks
+
+### Checking the translation progress
+
+```yaml
+name: Crowdin Action
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  crowdin:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Check translation progress
+        uses: crowdin/github-action@v1
+        with:
+          command: 'status translation'
+          command_args: '--fail-if-incomplete'
+```
+
+In the example above, the workflow will fail if the translation progress is less than 100%.
+
+Visit the [official documentation](https://crowdin.github.io/crowdin-cli/commands/crowdin-status) to learn more about the available translation status options.
+
+### Pre-Translation
+
+```yaml
+name: Crowdin Action
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  crowdin:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Pre-translate
+        uses: crowdin/github-action@v1
+        with:
+          command: 'pre-translate'
+          command_args: '--language uk --method tm'
+        env:
+          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
+```
+
+Visit the [official documentation](https://crowdin.github.io/crowdin-cli/commands/crowdin-pre-translate) to learn more about the available pre-translation options.
diff --git a/README.md b/README.md
@@ -11,24 +11,30 @@ A GitHub action to manage and synchronize localization resources with your Crowd
 [**`Configuration File`**](https://developer.crowdin.com/configuration-file/) |
 [**`Wiki`**](https://github.com/crowdin/github-action/wiki)
 
+[![test](https://github.com/crowdin/github-action/actions/workflows/test-action.yml/badge.svg)](https://github.com/crowdin/github-action/actions/workflows/test-action.yml)
 [![GitHub Used by](https://img.shields.io/static/v1?label=Used%20by&message=7k&color=brightgreen&logo=github&cacheSeconds=10000)](https://github.com/crowdin/github-action/network/dependents?package_id=UGFja2FnZS0yOTQyNTU3MzA0)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/crowdin/github-action?cacheSeconds=5000&logo=github)](https://github.com/crowdin/github-action/releases/latest)
-[![GitHub Release Date](https://img.shields.io/github/release-date/crowdin/github-action?cacheSeconds=5000)](https://github.com/crowdin/github-action/releases/latest)
 [![GitHub contributors](https://img.shields.io/github/contributors/crowdin/github-action?cacheSeconds=5000)](https://github.com/crowdin/github-action/graphs/contributors)
 [![GitHub](https://img.shields.io/github/license/crowdin/github-action?cacheSeconds=50000)](https://github.com/crowdin/github-action/blob/master/LICENSE)
 
 </div>
 
 ## What does this action do?
-- Uploads sources to Crowdin.
-- Uploads translations to Crowdin.
+
+This action allows you to easily integrate and automate the localization of your Crowdin project into the GitHub Actions workflow.
+
+- Upload sources to Crowdin.
+- Upload translations to Crowdin.
 - Downloads translations from Crowdin.
+- Download sources from Crowdin.
 - Creates a PR with the translations.
+- Run any Crowdin CLI command.
 
 ## Usage
+
 Set up a workflow in *.github/workflows/crowdin.yml* (or add a job to your existing workflows).
 
-Read the [Configuring a workflow](https://help.github.com/en/articles/configuring-a-workflow) article for more details on how to create and set up custom workflows.
+Read the [Configuring a workflow](https://help.github.com/en/articles/configuring-a-workflow) article for more details on creating and setting up GitHub workflows.
 
 ```yaml
 name: Crowdin Action
@@ -67,12 +73,9 @@ jobs:
 > **Note**
 > In case you want to use an [automatic GitHub authentication token](https://docs.github.com/en/actions/security-guides/automatic-token-authentication), you need to assign the [`write` permission to your job](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) and [allow GH Actions to create Pull Requests](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests).
 
-:file_folder: For more examples see the [EXAMPLES.md](/EXAMPLES.md)
-
-:clipboard: To explore the common questions about Crowdin GitHub Action usage visit the [Wiki](https://github.com/crowdin/github-action/wiki).
-
 ## Supported options
-The default action is to upload sources. Though, you can set different actions through the “with” options. If you don't want to upload your sources to Crowdin, just set the `upload_sources` option to false.
+
+The default action is to upload sources. However, you can set different actions using the "with" options. If you don't want to upload your sources to Crowdin, just set the `upload_sources` option to false.
 
 By default, sources and translations are being uploaded to the root of your Crowdin project. Still, if you use branches, you can set the preferred source branch.
 
@@ -82,6 +85,7 @@ In case you don’t want to download translations from Crowdin (`download_transl
 
 ```yaml
 - name: crowdin action
+  uses: crowdin/github-action@v1
   with:
     # Upload sources option
     upload_sources: true
@@ -126,18 +130,6 @@ In case you don’t want to download translations from Crowdin (`download_transl
     # If not specified default repository branch will be used.
     pull_request_base_branch_name: not_default_branch
 
-    # Branch options
-
-    add_crowdin_branch: branch_name
-    # Title as it appears to translators
-    new_branch_title: 'development / main'
-    # Defines branch name and path in resulting translations bundle
-    new_branch_export_pattern: '/translations/%two_letters_code%/%original_file_name%'
-    # [LOW, NORMAL, HIGH]
-    new_branch_priority: 'HIGH'
-
-    delete_crowdin_branch: branch_name
-
     # Global options
 
     # This is the name of the top-level directory that Crowdin will use for files.
@@ -160,22 +152,33 @@ In case you don’t want to download translations from Crowdin (`download_transl
     gpg_passphrase: ${{ secrets.GPG_PASSPHRASE }}
 
     # Config options
-
-    # The numeric project ID. Visit the Tools > API section in your Crowdin project
-    project_id: ${{ secrets.CROWDIN_PROJECT_ID }}
-
-    # A Personal Access Token (see https://crowdin.com/settings#api-key)
-    token: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
+    token: ${{ secrets.CROWDIN_PERSONAL_TOKEN }} # A Personal Access Token (see https://crowdin.com/settings#api-key)
+    project_id: ${{ secrets.CROWDIN_PROJECT_ID }} # The numeric project ID. Visit the Tools > API section in your Crowdin project
     source: 'path/to/your/file'
     translation: 'file/export/pattern'
-    base_url: 'https://crowdin.com'
-    base_path: 'project-base-path'
+    base_url: 'https://api.crowdin.com'
+    base_path: 'project-base-path' # Default: '.'
 ```
 
-**Note:** For Crowdin Enterprise `base_url` is required and should be passed in the following way: `base_url: 'https://{organization-name}.crowdin.com'`
-
 For more detailed descriptions of these options, see [`action.yml`](https://github.com/crowdin/github-action/blob/master/action.yml).
 
+> **Note**
+> The `base_url` is required For Crowdin Enterprise and should be passed in the following way: `base_url: 'https://{organization-name}.api.crowdin.com'`
+
+### Crowdin CLI command
+
+You can also run any other Crowdin CLI command by specifying the `command` and `command_args` _(optional)_ options. For example:
+
+```yaml
+- name: crowdin action
+  uses: crowdin/github-action@v1
+  with:
+    command: 'pre-translate'
+    command_args: '-l uk --method tm --branch main'
+```
+
+To see the full list of available commands, visit the [official documentation](https://crowdin.github.io/crowdin-cli/).
+
 ### Crowdin configuration file
 
 If your workflow file specifies the `config` property, you'll need to add the following to your [Crowdin configuration file](https://support.crowdin.com/configuration-file/) (e.g. `crowdin.yml`):
@@ -189,15 +192,14 @@ When the workflow runs, the real values of your token and project ID will be inj
 
 ## Contributing
 
-If you want to contribute please read the [Contributing](/CONTRIBUTING.md) guidelines.
+If you would like to contribute please read the [Contributing](/CONTRIBUTING.md) guidelines.
 
 ## Seeking Assistance
-If you find any problems or would like to suggest a feature, please feel free to file an issue on GitHub at [Issues Page](https://github.com/crowdin/github-action/issues).
 
-Need help working with Crowdin GitHub Action or have any questions?
-[Contact Customer Success Service](https://crowdin.com/contacts).
+If you find any problems or would like to suggest a feature, please feel free to file an issue on GitHub at [Issues Page](https://github.com/crowdin/github-action/issues).
 
 ## License
+
 <pre>
 The Crowdin GitHub Action is licensed under the MIT License.
 See the LICENSE file distributed with this work for additional