{"id":13539692,"url":"https://github.com/crowdin/github-action","last_synced_at":"2025-05-14T17:02:29.231Z","repository":{"id":37866083,"uuid":"258521306","full_name":"crowdin/github-action","owner":"crowdin","description":"A GitHub action to manage and synchronize localization resources with your Crowdin project","archived":false,"fork":false,"pushed_at":"2025-05-07T14:07:10.000Z","size":223,"stargazers_count":196,"open_issues_count":8,"forks_count":62,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-13T17:12:54.329Z","etag":null,"topics":["github-action","github-actions","hacktoberfest","localization","sync","translate"],"latest_commit_sha":null,"homepage":"https://crowdin.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crowdin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-04-24T13:33:35.000Z","updated_at":"2025-05-10T17:20:23.000Z","dependencies_parsed_at":"2023-10-27T10:57:44.910Z","dependency_job_id":"371726e8-9ade-4873-87df-85484120a4ec","html_url":"https://github.com/crowdin/github-action","commit_stats":{"total_commits":190,"total_committers":30,"mean_commits":6.333333333333333,"dds":"0.49473684210526314","last_synced_commit":"8dfaf9c206381653e3767e3cb5ea5f08b45f02bf"},"previous_names":[],"tags_count":94,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdin%2Fgithub-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdin%2Fgithub-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdin%2Fgithub-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowdin%2Fgithub-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crowdin","download_url":"https://codeload.github.com/crowdin/github-action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254190365,"owners_count":22029629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-action","github-actions","hacktoberfest","localization","sync","translate"],"created_at":"2024-08-01T09:01:30.442Z","updated_at":"2025-05-14T17:02:29.210Z","avatar_url":"https://github.com/crowdin.png","language":"Shell","readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://support.crowdin.com/assets/logos/symbol/png/crowdin-symbol-cWhite.png\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://support.crowdin.com/assets/logos/symbol/png/crowdin-symbol-cDark.png\"\u003e\n    \u003cimg width=\"150\" height=\"150\" src=\"https://support.crowdin.com/assets/logos/symbol/png/crowdin-symbol-cDark.png\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n# GitHub Crowdin Action [![Share](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?url=https%3A%2F%2Fgithub.com%2Fcrowdin%2Fgithub-action\u0026text=Easily%20integrate%20the%20localization%20of%20your%20Crowdin%20project%20into%20the%20GitHub%20Actions%20workflow)\u0026nbsp;[![GitHub Repo stars](https://img.shields.io/github/stars/crowdin/github-action?style=social\u0026cacheSeconds=1800)](https://github.com/crowdin/github-action/stargazers)\n\nA GitHub action to manage and synchronize localization resources with your Crowdin project\n\n\u003cdiv align=\"center\"\u003e\n\n[**`Examples`**](/docs/EXAMPLES.md) |\n[**`How to Set Up (video)`**](https://www.youtube.com/watch?v=5b7BMuCoKGg) |\n[**`Configuration File`**](https://developer.crowdin.com/configuration-file/) |\n[**`AI Localization`**](/docs/AI.md)\n\n[![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)\n[![GitHub Used by](https://img.shields.io/static/v1?label=Used%20by\u0026message=10k\u0026color=brightgreen\u0026logo=github\u0026cacheSeconds=10000)](https://github.com/crowdin/github-action/network/dependents?package_id=UGFja2FnZS0yOTQyNTU3MzA0)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/crowdin/github-action?cacheSeconds=5000\u0026logo=github)](https://github.com/crowdin/github-action/releases/latest)\n[![GitHub contributors](https://img.shields.io/github/contributors/crowdin/github-action?cacheSeconds=5000)](https://github.com/crowdin/github-action/graphs/contributors)\n[![GitHub](https://img.shields.io/github/license/crowdin/github-action?cacheSeconds=50000)](https://github.com/crowdin/github-action/blob/master/LICENSE)\n\n\u003c/div\u003e\n\n## What does this action do?\n\nThis action allows you to easily integrate and automate the localization of your Crowdin project into the GitHub Actions workflow.\n\n- Upload sources to Crowdin.\n- Upload translations to Crowdin.\n- Downloads translations from Crowdin.\n- Download sources from Crowdin.\n- Creates a PR with the translations.\n- Run any [Crowdin CLI](https://crowdin.github.io/crowdin-cli/commands/crowdin) command.\n\n## Usage\n\nSet up a workflow in *.github/workflows/crowdin.yml* (or add a job to your existing workflows).\n\nRead the [Configuring a workflow](https://help.github.com/en/articles/configuring-a-workflow) article for more details on creating and setting up GitHub workflows.\n\n### Sample workflow\n\n```yaml\nname: Crowdin Action\n\non:\n  push:\n    branches: [ main ]\n\njobs:\n  synchronize-with-crowdin:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: crowdin action\n        uses: crowdin/github-action@v2\n        with:\n          upload_sources: true\n          upload_translations: false\n          download_translations: true\n          localization_branch_name: l10n_crowdin_translations\n          create_pull_request: true\n          pull_request_title: 'New Crowdin Translations'\n          pull_request_body: 'New Crowdin translations by [Crowdin GH Action](https://github.com/crowdin/github-action)'\n          pull_request_base_branch_name: 'main'\n        env:\n          # A classic GitHub Personal Access Token with the 'repo' scope selected (the user should have write access to the repository).\n          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}\n          \n          # A numeric ID, found at https://crowdin.com/project/\u003cprojectName\u003e/tools/api\n          CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}\n\n          # Visit https://crowdin.com/settings#api-key to create this token\n          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}\n```\n\nCreate the `CROWDIN_PROJECT_ID` and `CROWDIN_PERSONAL_TOKEN` secrets in Repository settings -\u003e Secrets and variables -\u003e Actions \u003e Repository secrets.\n\n\u003e [!TIP]\n\u003e When creating a personal token in Crowdin, you'll be asked to select the necessary scopes. The basic Crowdin Personal Token scopes are the following:\n\u003e\n\u003e - **Projects** (List, Get, Create, Edit) -\u003e Read\n\u003e - **Translation Status** -\u003e Read Only\n\u003e - **Source files \u0026 strings** -\u003e Read and Write\n\u003e - **Translations** -\u003e Read and Write\n\u003e\n\u003e Please note that these scopes may vary depending on the actions you want to perform.\n\n\u003e [!NOTE]\n\u003e For fully automated AI localization with Crowdin, check out the [AI Localization](/docs/AI.md) guide.\n\n### Sample `crowdin.yml` configuration file\n\n```yaml\n\"project_id_env\": \"CROWDIN_PROJECT_ID\"\n\"api_token_env\": \"CROWDIN_PERSONAL_TOKEN\"\n\"base_path\": \".\"\n\n\"preserve_hierarchy\": true\n\n\"files\": [\n  {\n    \"source\": \"locales/en.yml\",\n    \"translation\": \"locales/%two_letters_code%.yml\"\n  }\n]\n```\n\nReplace the `source` and `translation` paths with the actual paths to your source and translation files.\n\nBy default, the action will look for the `crowdin.yml` file in the root of the repository. You can specify a different path using the `config` option.\n\n\u003e [!CAUTION]\n\u003e Make sure you use environment variables and do not hardcode your Crowdin API token in the configuration file.\n\n## Supported options\n\n### Upload options\n\n| Option                     | Description                                                                                        | Example value                |\n|----------------------------|----------------------------------------------------------------------------------------------------|------------------------------|\n| `upload_sources`           | Specifies whether or not to upload sources to Crowdin                                              | `true` (default)             |\n| `upload_translations`      | Specifies whether or not to upload existing translations to Crowdin                                | `false` (default)            |\n| `upload_language`          | Upload translations for a single specified language                                                | `uk`                         |\n| `auto_approve_imported`    | Automatically approve added translations                                                           | `false` (default)            |\n| `import_eq_suggestions`    | Add translations even if they match the source strings                                             | `false` (default)            |\n| `upload_sources_args`      | Allows passing any supported arguments of the [`upload sources`][upload-sources] command           | `--no-auto-update label=web` |\n| `upload_translations_args` | Allows passing any supported arguments of the [`upload translations`][upload-translations] command | `--translate-hidden`         |\n\n### Download options\n\n| Option                       | Description                                                                                            | Example value                       |\n|------------------------------|--------------------------------------------------------------------------------------------------------|-------------------------------------|\n| `download_sources`           | Specifies whether to download sources from Crowdin                                                     | `false` (default)                   |\n| `download_translations`      | Specifies whether to download translations from Crowdin                                                | `false` (default)                   |\n| `download_bundle`            | The numeric ID of the Bundle you want to download translations from                                    | `1`                                 |\n| `download_language`          | Download translations for a single specified language                                                  | `uk`                                |\n| `skip_untranslated_strings`  | Skip untranslated strings when downloading translations                                                | `false` (default)                   |\n| `skip_untranslated_files`    | Skip untranslated files when downloading translations                                                  | `false` (default)                   |\n| `export_only_approved`       | Include only approved translations in exported files                                                   | `false` (default)                   |\n| `download_sources_args`      | Allows passing any supported arguments of the [`download sources`][download-sources] command           | `--reviewed`                        |\n| `download_translations_args` | Allows passing any supported arguments of the [`download translations`][download-translations] command | `--all --skip-untranslated-strings` |\n\n### Git and Pull Request options\n\n| Option                          | Description                                                                                                  | Example value                                         |\n|---------------------------------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|\n| `push_translations`             | Push downloaded translations to the localization branch                                                      | `true` (default)                                      |\n| `push_sources`                  | Push downloaded sources to the localization branch                                                           | `true` (default)                                      |\n| `localization_branch_name`      | The name of the git branch that Crowdin will create when pushing translations or sources                     | `l10n_crowdin_action` (default)                       |\n| `commit_message`                | The commit message for the pushed changes                                                                    | `New Crowdin translations by GitHub Action` (default) |\n| `create_pull_request`           | Specifies whether to create a pull request with the translations                                             | `true` (default)                                      |\n| `pull_request_title`            | The pull request title                                                                                       | `New Crowdin translations by GitHub Action` (default) |\n| `pull_request_body`             | The pull request body                                                                                        | `New Crowdin pull request with translations`          |\n| `pull_request_labels`           | The pull request labels                                                                                      | `localization, l10n`                                  |\n| `pull_request_assignees`        | The pull request assignees                                                                                   | `crowdin-bot`                                         |\n| `pull_request_reviewers`        | The pull request reviewers                                                                                   | `user-reviewer`                                       |\n| `pull_request_team_reviewers`   | The pull request team reviewers                                                                              | `team-reviewer`                                       |\n| `pull_request_base_branch_name` | The base branch that the pull request will target. If not specified, the default branch is used              | `main`                                                |\n| `skip_ref_checkout`             | Skip the default git checkout on `GITHUB_REF` if you need to checkout multiple branches in a single workflow | `false` (default)                                     |\n\n### Global options\n\n| Option                 | Description                                                                                | Example value              |\n|------------------------|--------------------------------------------------------------------------------------------|----------------------------|\n| `crowdin_branch_name`  | Option to upload or download files to the specified version branch in your Crowdin project | `main`                     |\n| `config`               | Option to specify a path to the configuration file (without `/` at the beginning)          | `path/to/your/crowdin.yml` |\n| `dryrun_action`        | Defines whether to run the action in the dry-run mode                                      | `false` (default)          |\n\n### GitHub (Enterprise) configuration\n\n| Option                | Description                                                                                                                | Example value                       |\n|-----------------------|----------------------------------------------------------------------------------------------------------------------------|-------------------------------------|\n| `github_base_url`     | Option to configure the base URL of GitHub server, if using GitHub Enterprise                                              | `github.com` (default)              |\n| `github_api_base_url` | Options to configure the base URL of GitHub server for API requests, if using GHE and different from `api.github_base_url` | `api.[github_base_url]`             |\n| `github_user_name`    | Option to configure GitHub user name on commits                                                                            | `Crowdin Bot` (default)             |\n| `github_user_email`   | Option to configure GitHub user email on commits                                                                           | `support+bot@crowdin.com` (default) |\n| `gpg_private_key`     | GPG private key in ASCII-armored format                                                                                    | `${{ secrets.GPG_PRIVATE_KEY }}`    |\n| `gpg_passphrase`      | The passphrase for the ASCII-armored key                                                                                   | `${{ secrets.GPG_PASSPHRASE }}`     |\n\n\u003e [!NOTE]\n\u003e For signed commits, add your ASCII-armored key and export `gpg --armor --export-secret-key GPG_KEY_ID`\n\u003e\n\u003e Ensure that all emails are the same: for account profile that holds private key, the one specified during key generation, and for commit author (`github_user_email` parameter)\n\n### CLI config options\n\n| Option          | Description                                                              | Example value                            |\n|-----------------|--------------------------------------------------------------------------|------------------------------------------|\n| `token`         | Crowdin Personal Access Token                                            | `${{ secrets.CROWDIN_PERSONAL_TOKEN }}`  |\n| `project_id`    | The numeric project ID (_Tools_ \u003e _API_ section in your Crowdin project) | `${{ secrets.CROWDIN_PROJECT_ID }}`      |\n| `source`        | Path to the source files (without `/` at the beginning)                  | `sources/pattern`                        |\n| `translation`   | Path to the translation files                                            | `translations/pattern`                   |\n| `base_url`      | Base URL of Crowdin server for API requests execution                    | `https://api.crowdin.com`                |\n| `base_path`     | The project base path                                                    | `.`                                      |\n\nThe options above can be used in the [No-crowdin.yml configuration](/docs/EXAMPLES.md#no-crowdinyml-configuration) mode.\n\n\u003e [!NOTE]\n\u003e The `base_url` is required For Crowdin Enterprise and should be passed in the following way: `base_url: 'https://{organization-name}.api.crowdin.com'`\n\n### Crowdin CLI command\n\nYou can also run any other Crowdin CLI command by specifying the `command` and `command_args` _(optional)_ options. For example:\n\n```yaml\n- name: crowdin action\n  uses: crowdin/github-action@v2\n  with:\n    command: 'pre-translate'\n    command_args: '-l uk --method tm --branch main'\n```\n\nTo see the full list of available commands, visit the [official documentation](https://crowdin.github.io/crowdin-cli/).\n\n## Outputs\n\nThis action has the following outputs:\n\n- `pull_request_url`: The URL of the pull request created by the workflow\n- `pull_request_number`: The number of the pull request created by the workflow\n\n## Permissions\n\nIn order to push translations and create pull requests, the Crowdin GitHub Action requires the `GITHUB_TOKEN` to have the write permission on the `contents` and `pull-requests`.\n\nIn 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).\n\n## Migration from the native GitHub integration\n\nIf you are using the [native GitHub integration](https://store.crowdin.com/github), you can easily migrate to the GitHub Action. The main difference is that the GitHub Action requires a Crowdin Personal Access Token and a numeric project ID to be specified. Follow the steps below to migrate:\n\n- If you're using a `crowdin.yml` file, you'll need to add `preserve_hierarchy: true` to keep the directory structure the same between Crowdin and GitHub (even if you weren't already using this setting in your existing OAuth integration).\n- `localization_branch_name` should be set to the existing Git branch name you're using for Crowdin PRs.\n- `crowdin_branch_name` should be set as well.\n\nFor example, if you have the following configuration file:\n\n```yaml\nfiles:\n  - source: /**/*.xml\n    translation: /**/%two_letters_code%.xml\n```\n\nAdd the credentials:\n\n```yaml\nproject_id_env: CROWDIN_PROJECT_ID\napi_token_env: CROWDIN_PERSONAL_TOKEN\n\nfiles:\n  - source: /**/*.xml\n    translation: /**/%two_letters_code%.xml\n```\n\nThen create the secrets `CROWDIN_PROJECT_ID` and `CROWDIN_PERSONAL_TOKEN` and finally, create the workflow. See [Usage](#usage) for more details.\n\nIf comparing the native GitHub integration and the GitHub Action, the GitHub Action provides more flexibility and control over the localization process.\n\n## Contributing\n\nIf you would like to contribute, please read the [Contributing](/CONTRIBUTING.md) guidelines.\n\n## Seeking Assistance\n\nIf you find any problems or would like to suggest a feature, please feel free to file an issue on GitHub at the [Issues Page](https://github.com/crowdin/github-action/issues). Please also check the [Examples](/docs/EXAMPLES.md) page for more use cases.\n\n## License\n\n\u003cpre\u003e\nThe Crowdin GitHub Action is licensed under the MIT License.\nSee the LICENSE file distributed with this work for additional\ninformation regarding copyright ownership.\n\nExcept as contained in the LICENSE file, the name(s) of the above copyright\nholders shall not be used in advertising or otherwise to promote the sale,\nuse or other dealings in this Software without prior written authorization.\n\u003c/pre\u003e\n\n[upload-sources]: https://crowdin.github.io/crowdin-cli/commands/crowdin-upload-sources\n[upload-translations]: https://crowdin.github.io/crowdin-cli/commands/crowdin-upload-translations\n[download-sources]: https://crowdin.github.io/crowdin-cli/commands/crowdin-download-sources\n[download-translations]: https://crowdin.github.io/crowdin-cli/commands/crowdin-download-translations\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdin%2Fgithub-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrowdin%2Fgithub-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdin%2Fgithub-action/lists"}