GitHub (Strings)

Content is machine translated from English by Phrase Language AI.

Tip

For information about GitHub integration in Phrase TMS, refer to GitHub (TMS).

Phrase Strings integrates with GitHub repositories to synchronize localization files between Phrase and GitHub.

By default, repositories are connected using a GitHub OAuth App. Personal access tokens are also supported and are mainly intended for self-hosted instances or environments where OAuth App installation is not possible.

Prerequisites

The .phrase.yml configuration file must be present in the root of the branch to be monitored. The file defines which files to import (pull) or export (push) from the repository.
Read and write access are required for the repository.
Incorrectly defined configuration files may cause errors. Ensure that the file contains at least one push and one pull target, correct file formats and the correct setting of the update_translations parameter.
GitHub OAuth App:
- The GitHub OAuth App must be installed in the GitHub organization or account that owns the repository.
- The repository must be included in the OAuth App installation.
- Permissions to install or authorize GitHub Apps are required in the target organization or account.
GitHub access token:
- Classic tokens
  
  Requires the repo scope (public_repo if synchronizing with a public repository)
- Fine-grained tokens
  
  Requires the following permissions:
  - Contents: Read and write
  - Pull requests: Read and write
- Ensure repository settings do not require signed commits.
If SSO is enabled in GitHub, it must also be enabled for the access token.
The phrase_translations branch cannot be protected.

Note

Due to continuous improvements, the user interface may not be exactly the same as presented in the video.

Connect Repositories

Once the configuration file is in place, to connect a repository, follow these steps:

From the Integrations page, scroll down to Repo Sync and click Configure.

The Repo Syncs page opens.
Click Add Sync/GitHub.

The GitHub sync settings window opens.
Select a project from the dropdown list.
Select the authentication method:
- GitHub App (recommended)
  
  If the GitHub App is not yet installed, click Authenticate. Authentication is performed once and can be reused for multiple repository syncs.
  
  If the GitHub App is already installed, click Manage installation to complete the app installation for the target organization or account. Repository access is managed at the organization or account level and is not tied to an individual GitHub user.
- Personal access token
  
  Provide a personal Repo access token with an API scope.
  
  When using a personal access token, repository access depends on the GitHub user who created the token.
- Self-hosted instance
  
  Provide the GitHub self-hosted API endpoint and a personal Repo access token with an API scope.
Select a GitHub repository from the dropdown list.
Select a Repository branch from the dropdown list to import (push) and export (pull) from. This is usually the master branch.
Optionally, provide a branch name for the pull request. If left empty, a branch will be created with the default value phrase-translations.
Click Validate Configuration to ensure authentication settings and configuration file are correct.
Optionally select an Import behavior option to determine when new or updated files are automatically imported in the project.
Click Save.

The project is now connected to the selected GitHub repository and added to the list.
(Optional) Click the pencil icon to rename the integration.

Import Files

Ensure the push commands are correctly configured within the .phrase.yml configuration file. Push options are the same as for the uploads API endpoint.

To import files:

From the Repo Syncs page, select a project and click Import .

Language files (defined as push source entries in the configuration file) are imported into the project.

A default locale must be present.

Note

In case of issues upon importing, use the CLI client to test the .phrase.yml configuration file locally and check for any error messages.

If required, contact Phrase Technical Support and attach the .phrase.yml configuration file to the support request.

Export Files

Ensure the pull commands are correctly configured within the .phrase.yml configuration file. Pull options (e.g. include_empty_translations parameter) are the same as for the locales download API endpoint.

To export files:

From the Repo Syncs page, select a project and click Export .

The Export window is displayed.
Provide the target branch in the PR branch field.

The most recent files in the repository will be exported as a new pull request to the desired branch.
Once files are exported, the pull request can be merged or closed in the repository and the branch can be deleted.

Note

In case of issues upon exporting, use the CLI client to test the .phrase.yml configuration file locally and check for any error messages.

If required, contact Phrase Technical Support and attach the .phrase.yml configuration file to the support request.

History

Repo syncs keep a history of the latest imports and exports for each Phrase Strings project.

To view the history:

From the Repo Syncs page, select a project and click History .

The import and export history for the project is presented. Export entries in the history include a link to the corresponding merge request.