GitHub connector

1 How it Works
2 Create a Configuration
3 Creating Repository Configurations
4 The Configuration File
5 The Delivery Mechanism

The BWX GitHub connector (GHC) creates translation Projects from files in GitHub repositories, using a descriptive YAML configuration that is deployed alongside the repository files.

How it Works

The GHC actively monitors a GitHub repository for updates in tracked files. Given a certain schedule, compatible with project needs when it comes to the file translation frequency, the GHC will scan the repository and compare the files with previous records in BWX. If a change is detected (by using a hashing function), the files are automatically added to a new project in BWX for translation the pre-determined target languages set.

You can also trigger the scan manually using the BWX user interface, we will explore this option further in this document.

There are a few steps to configure the connector:

Create a Configuration for your repository
Create a Repository configuration
Add the configuration file to your repository

Create a Configuration

Go to Connectors > GitHub > Config and click Add Configuration

Select an Organizational Unit. This will determine which department or, well, organizational unit will be the owner of the newly created Projects, which will inherit all configuration related to Translation Memories, Glossaries, etc.
Give a Name to this configuration
For the URL, leave it as-is unless you have a GitHub Enterprise account and a custom URL for your APIs.
Username is your GitHub username. For organizations, we recommend the creation of a service account, with its scope limited to the repositories of interest for better security.
GitHub Token is a Personal Access Token that can be generated specifically for this integration, with the repo scope only. You can read more about how to create and manage PATs here: https://docs.github.com/en/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Security note: tokens are encrypted at rest, and are only used by the GHC to access the repository during sync operations.

You can also use our API to create the same Configuration with the endpoint POST /api/v3/connector/github/config. This endpoint expects a body in the following format:

    {
      "orgUnitUuid": "string",
      "githubUrl": "string",
      "githubUser": "string",
      "githubToken": "string"
    }

orgUnitUuid - the UUID of the Org Unit you’re creating the configuration for. This information can be easily retrieved in the Org Unit’s URL:
githubUrl - this is the GitHub API URL of your organization. Leave this field null if your organization doesn’t have a custom GitHub API, so it defaults to https://api.github.com
githubUser - this is the username GHC is gonna use to connect to GitHub
githubToken - this is the token GHC is gonna use to connect to GitHub

Creating Repository Configurations

Once a Configuration is created, you can create multiple repository configurations. You can monitor as many GitHub repositories as you want. Select your Configuration, click in Add Configuration under Repository Configurations to start the wizard.

For repository name and owner, take our CLI for example, which leaves under https://github.com/bureauworks/cli

The owner is bureauworks

The name is cli

Click Next

The base branch represents the GitHub branch that must be monitored for changes. Common values here are master, main or develop. The GHC will use this branch to find the files, and to eventually create Pull Requests for delivering projects.

The Config Path is the relative to the root path of the YAML file containing the localization files and target languages. We will explore this file’s structure in a bit.

Finally, the CI (Continuous Integration) Tag. This tag will uniquely identify a class of projects within your continuous projects. For example, let’s say you have 2 repositories for your app, one iOS and one for Android. You will have 2 repository configurations, and you can use the CI Tag ios for one and android for the other, to easily spot and separate this projects as they are created in BWX.

New configurations can also be added through the endpoint POST /api/v3/connector/github/config/{orgUnitUUID}/repo which expects a list of configuration objects:

[
  {
    "name": "string",
    "owner": "string",
    "baseBranch": "string",
    "projectTag": "string",
    "configPath": "string"
  }
]

name and owner - define the identifier of the GitHub repository.
baseBranch - the branch GHC will pull data from
projectTag - the BWX’s Continuous Project tag. Every file pulled from GitHub will be sent to a DRAFT project identified by projectTag
configPath - the location of the configuration file in the repository. This file contains the paths of all the files that are to be translated and all target locales they’re to be translated to.

The Configuration File

The configuration file that is to reside in your repository tells GHC which files need to be translated and to what languages. It’s a YML file that can be located anywhere in your repo - GHC will look for the file in configPath defined in the previous section.

This is how this should look like:

---
github_repo: owner/name
filenameLanguageSeparator: ~
sourceLocale:
  key: en
  tms: en_us
locales:
- key: cs
  tms: cs_cz
- key: da
  tms: da_dk
sources:
- defaultOutputPathPattern: "{lang}/{filename}"
  sourceFiles:
  - path: en/test.yml
  - path: en/test.json
- defaultOutputPathPattern: "{lang}/{filename}"
  filenameLanguageSeparator: "."
  sourceFiles:
  - path: en/test.en.yml

sourceLocale - the source locale of the files to be translated. It’s an object with key and tms properties:
- key - the language code in your repository or system, if different. This value can be the same as the value in tms
- tms - the language code in BWX
filenameLanguageSeparator - this is the separator used if your filenames contain the language code in them. Leave this null (or ~), or even ignore it, if that’s not the case. If this is defined here, it'll be used for all filenames
locales - the target locales your files will be translated into. It’s a list of objects respecting the same syntax as sourceLocale
sources - a list of objects that will be translated.
- defaultOutputPathPattern - how GHC will build the output path of each translated file. It handles three masks:
  - {lang} - will be replaced with the target locale key property
  - {target} - same as {lang}
  - {filename} - the filename of the translated file - if not null, filenameLanguageSeparator will be considered when building the target filename
- filenameLanguageSeparator - to be used in the filenames of this group only
- sourceFiles - a list of the files that will be translated

The Delivery Mechanism

When a GitHub integration project is finalized in Bureau Works, the GHC will create a new branch in the repository, named after the project itself. Then, a new pull request will be created that makes it easy to compare updates with existing files, or entirely new translations being delivered.

After a successful run of the GHC for this configuration file, for example, a pull request will be created with the following translated files:

cs/test.yml
cs/test.json
da/test.yml
da/test.json
cs/test.cs.yml
da/test.da.yml