Crowdin github action

The modernization of software delivery pipelines necessitates a seamless bridge between development and localization. For organizations managing multi-lingual applications, the manual export and import of translation files represent a significant bottleneck, prone to human error and version drift. The Crowdin GitHub Action emerges as a sophisticated orchestration tool designed to eliminate these frictions by integrating the Crowdin localization management system directly into the GitHub Actions CI/CD ecosystem. By transforming localization from a sporadic manual task into a continuous automated process, developers can ensure that the latest source strings are always available for translators and that the most recent translations are merged into the codebase without manual intervention.

This integration operates as a specialized workflow runner that leverages the Crowdin API to synchronize files between a GitHub repository and the Crowdin project environment. Unlike static integrations, this action allows for granular control over when sources are uploaded and when translations are pulled back, enabling a "Localization-as-Code" approach. This means that the entire translation lifecycle—from the moment a developer commits a new string in a .json or .xml file to the moment a translator approves a localized version—is governed by the same version control logic and automation triggers as the primary application code.

Core Functional Capabilities

The Crowdin GitHub Action is not a singular task but a multi-functional toolset capable of executing various synchronization operations. The scope of its capabilities ensures that every stage of the localization pipeline is covered.

• Upload sources to Crowdin: This function scans the repository for source files and pushes them to the Crowdin project. This ensures translators are always working on the most current version of the text.
• Download translations from Crowdin: This operation pulls the approved translations from the Crowdin platform and writes them back into the repository.
• Upload translations to Crowdin: This allows users to push existing translation files from the repository into the Crowdin environment.
• Download sources from Crowdin: This permits the retrieval of original source files from the Crowdin project back into the local repository context.
• Create Pull Requests (PRs): The action can automatically open a PR containing the downloaded translations, allowing developers to review changes before merging them into the main branch.
• Execute Crowdin CLI commands: For advanced users, the action can be used to run any command available in the Crowdin Command Line Interface, providing an escape hatch for custom automation needs.

Technical Implementation and Workflow Configuration

Implementing the Crowdin GitHub Action requires the creation of a YAML configuration file located within the .github/workflows/ directory. The standard filename is crowdin.yml, although any valid YAML name may be used.

The workflow is typically triggered by a push event on a specific branch, such as main, ensuring that every update to the source code triggers a synchronization check. The execution environment relies on ubuntu-latest, providing a standardized Linux runner for the action to operate.

A comprehensive implementation of the workflow is detailed in the following configuration:

yaml name: Crowdin Action on: push: branches: [ main ] jobs: synchronize-with-crowdin: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: crowdin action uses: crowdin/github-action@v2 with: upload_sources: true upload_translations: false download_translations: true localization_branch_name: l10n_crowdin_translations create_pull_request: true pull_request_title: 'New Crowdin Translations' pull_request_body: 'New Crowdin translations by [Crowdin GH Action](https://github.com/crowdin/github-action)' pull_request_base_branch_name: 'main' env: GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }} CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

Deep Dive into Configuration Parameters

To achieve precise control over the localization flow, the with block provides several options that dictate the behavior of the action.

The upload_sources parameter is a boolean value. When set to true, the action uploads source files to Crowdin. If the user wishes to disable this behavior to prevent overwriting or to manage uploads manually, it must be set to false. By default, these sources are uploaded to the root of the Crowdin project.

The download_translations parameter controls whether the action pulls translated files from the Crowdin project back into the GitHub repository. This is critical for closing the loop in the localization process.

The create_pull_request parameter, when enabled, automates the delivery of translations. Instead of committing directly to a branch, the action opens a formal PR. This is governed by the following supporting parameters:

• localization_branch_name: Defines the branch where the downloaded translations will be committed (e.g., l10n_crowdin_translations).
• pull_request_title: The headline of the generated PR, such as 'New Crowdin Translations'.
• pull_request_body: The descriptive text within the PR, typically including a link back to the action for traceability.
• pull_request_base_branch_name: The target branch the PR intends to merge into, usually main.

Environmental Variables and Security Requirements

The security of the localization pipeline relies on the use of GitHub Secrets to handle sensitive credentials. The action requires three specific environment variables to authenticate and identify the target project.

The use of ${{ secrets.VARIABLE_NAME }} ensures that these tokens are never exposed in plain text within the YAML file, mitigating the risk of credential leakage.

Migration from Native GitHub Integration to GitHub Action

Many users may transition from the native Crowdin-GitHub OAuth integration to the GitHub Action for increased flexibility and control. This migration requires specific adjustments to the project configuration.

The primary difference lies in the authentication method; while the native integration uses OAuth, the action requires a numeric project ID and a Personal Access Token.

For users utilizing a crowdin.yml configuration file, the following steps are mandatory for a successful migration:

• The preserve_hierarchy: true setting must be added to the crowdin.yml file. This ensures that the directory structure remains consistent between the GitHub repository and the Crowdin platform, regardless of whether this was enabled in the previous OAuth setup.
• The localization_branch_name must be mapped to the existing Git branch used for Crowdin PRs.
• The crowdin_branch_name should also be specified to maintain consistency.

An example of a migrated crowdin.yml configuration is presented below:

yaml project_id_env: CROWDIN_PROJECT_ID api_token_env: CROWDIN_PERSONAL_TOKEN files: - source: /**/*.xml translation: /**/%two_letters_code%.xml preserve_hierarchy: true

In this scenario, the configuration targets all .xml files recursively and maps the translations using a two-letter language code pattern.

Advanced Integration: Private Enterprise Repositories and Webhooks

A common challenge for enterprise users is triggering GitHub Actions based on events occurring within the Crowdin platform, especially when working with private GitHub Enterprise repositories. Since GitHub Actions are typically triggered by Git events, a bridge is needed to notify GitHub when a translation has been updated in Crowdin.

The recommended architecture for this requirement is the implementation of Webhooks. Crowdin can be configured to send a webhook notification to a specific endpoint whenever a source file is updated or a translation is completed.

The workflow for this integration is as follows:

• A Webhook is configured in the Crowdin project settings.
• The Webhook is pointed toward a GitHub endpoint or a middleware service capable of triggering a repository_dispatch event.
• The GitHub Action is configured to trigger on the repository_dispatch event, allowing the Crowdin update to kick off the synchronize-with-crowdin job automatically.

This setup ensures that the synchronization is not just scheduled or based on code pushes, but is truly event-driven, reflecting real-time changes from the translation team.

Comparison of Integration Methods

The choice between the native integration and the GitHub Action depends on the level of control required by the development team.

The GitHub Action provides superior flexibility, allowing developers to decide exactly when synchronization occurs and how the resulting files are merged into the codebase.

Conclusion: Strategic Analysis of the Localization Pipeline

The integration of the Crowdin GitHub Action represents a shift toward a more mature DevOps approach to localization. By treating translation files as first-class citizens in the version control system, organizations can eliminate the "localization lag" that often occurs at the end of a release cycle. The ability to automate the upload of sources ensures that translators never work on outdated strings, while the automated PR process ensures that localized content is reviewed and merged with the same rigor as feature code.

From a technical perspective, the reliance on ubuntu-latest and the actions/checkout@v4 ensures that the environment is stable and up-to-date. The requirement for preserve_hierarchy: true during migration highlights the importance of structural integrity in localization; without it, the mapping between the source and translation files can break, leading to broken paths and failed builds.

Ultimately, the move toward the GitHub Action, especially when combined with Webhooks for private enterprise repositories, transforms localization from a manual bottleneck into a streamlined, automated pipeline. This not only increases the velocity of international releases but also improves the quality of the final product by ensuring a tighter feedback loop between developers and linguists.

Sources

1. Crowdin Store - GitHub Action
2. Crowdin GitHub Repository
3. GitHub Marketplace - Crowdin Action
4. Crowdin GitHub Action Discussions
5. Crowdin Community - Triggering Actions from Private Enterprise Repos