GitHub connector

Introduction

The TranslationOS connector for GitHub makes it easy to entrust Translated with the professional or automated translation of your string resources and documents, saving you the hassle of importing and exporting content or switching between tools.

This connector can be configured to be event- or polling-based, meaning it can be triggered by specific actions or set up to fetch content at intervals. To learn which actions trigger the connector, see the section Requesting translations.

Support

For general questions about functionality, our dedicated support team can be reached at info-tos@translated.com.

If you need technical information or you’re ready to integrate GitHub with TranslationOS, feel free to reach out to us at api@translated.com for assistance with onboarding.

The onboarding process may vary depending on your needs, but the following steps are a helpful guideline:

1. You will agree with Translated on the required service levels, also known as service types.

2. Translated will analyse your files and build any custom parsers required.

3. You will install the connector app in your GitHub repository.

4. Translated will help you set up projects and filesets—including custom parsers, pluralisation handling and URL pre-processing—and configure the fetching and delivery methods.

5. We will be ready to receive, process and deliver your translation requests!

Setting up the connector

The first step is to analyse your files and determine whether custom parsers are required. Once any custom parsers have been built, you will need to install an app in your GitHub repository. With that done, we will work with you to set up projects and filesets, and to configure the fetching and delivery methods.

Analysing your files

TranslationOS natively supports a wide range of file types. See the content_type field of the /translate endpoint.

If your files make use of an unsupported standardised structure or custom structure, we will need to build a custom parser for you. See here for the custom parsers that are currently supported.

Installing the GitHub app

Translated will provide you with a link to the connector’s GitHub app. You will need to install it and grant it the required permissions. The app will install a webhook subscribed to push events.

Creating projects

Projects are the main unit of the GitHub connector. A project is associated with a single branch in a repository. It is used to configure the:

• repository information

• filesets to observe

• observed branch

• delivery branch (may be the same as the observed branch)

• fetching and delivery methods

• source language

• target languages

• TranslationOS metadata such as service type, instructions and invoicing information

More than one project may be configured in a repository, so care must be taken to ensure that they don’t overlap or interfere with each other. No automated mechanism is in place to do this.

Specifying filesets

A fileset specifies the files to observe within a project and how to handle them. In particular, you can specify the:

• paths and names of the source files using a pattern supporting wildcards

• paths and names of the target files using a pattern supporting placeholders

• file type: string resource or document

• applicable parser in the case of string resources, or content type in the case of documents

• handling of missing or outdated translations at delivery

  • missing translations

    • upload the source text

    • omit the key

  • outdated translations

    • upload the latest available translation

    • upload the source text

    • omit the key

• URL pre-processing rules, allowing for automatic localisation of regularly-structured URLs

More than one fileset may be configured in a project, so each file must only be captured in a single fileset. There is no automated mechanism to check that there is no overlap.

Configuring fetch/delivery methods

The GitHub connector supports three fetch and delivery methods.

Fetch on change

Whenever a commit is made to an observed source file, the file is processed by the connector.

In the case of string resources, new and edited strings are fetched. The connector also keeps track of any deleted strings to ensure they can’t be delivered again.

Documents are directly sent for translation.

Delivery on completion

Files are uploaded to the delivery branch once there are no more translations pending.

Periodic fetching/delivery

A scheduler initiates fetches or delivery at regular intervals.

Manual fetching/delivery

You explicitly trigger a fetch or delivery from the UI or via API for a specific project.

Initial synchronisation

When a project is created, the connector synchronises with the observed branch according to the configured filesets. The purpose is solely to identify any missing target content; ingestion isn’t performed.

String resources

Each resource file is deconstructed. If a resource file lacks a matching target, all the keys are marked as missing. If it has a matching target, the connector checks whether each key has a counterpart in the target. If so, the existing translation is imported. If not, the key is marked as missing, meaning that it will be sent for translation when ingestion is triggered.

Documents

The connector records all documents as missing, since even if there is a corresponding target, it has no way to verify whether it actually contains a translation of the source.

Using the connector

Requesting translations

At each commit made to a project’s observed branch, source files are checked for changes. If a document or any keys in a string resource have changed, they are sent for translation. The target files aren’t checked.

If the same document or string resource key is changed and fetched several times, the connector uses version control to ensure that only the translations of the latest version of the source can be delivered.

Receiving the translated content

At delivery, the connector creates a new target file if it doesn’t exist, or it replaces any existing target file based on the content of the connector’s database. The connector doesn’t make pull requests; it directly commits the target files.

In the case of string resources, if any translations are missing or outdated at delivery, the behaviour defined in the fileset is applied.

Any changes made to target files between intake and delivery are overwritten. If you need to make amendments to the translations, please do so directly in TranslationOS to ensure that they are preserved.

Cancelling translations

In-queue requests can be cancelled on TranslationOS. All other cancellation requests require the intervention of the project manager.

At the next intake, since the connector uses the source hash to determine whether there is any new content to fetch, the documents or keys corresponding to the deleted requests are only fetched if the source file has since been modified. They are not automatically ingested again at the next polling cycle.

FAQ

How do I track my assets in TranslationOS?

TranslationOS uses abstract concepts like content ID, order ID and order group ID to map your content. The values for these fields change depending on the source platform. To retrieve a GitHub order in TranslationOS, use the Requests or Content views in TranslationOS and search by any of the values in the table below.

String resource

Document

Which placeholders are supported in target file naming rules?

• language name

• original file name with extension

• original file extension

• original file name without extension

• ISO 639-1 language code

• ISO 639-1 country code

• country name

• ISO 3166 alpha-2 country code

Which string resource parsers are supported?

The GitHub connector currently supports these parsers:

• Android strings (.xml) with pluralisation handled as per CLDR 44

• iOS strings (.strings)

• iOS string dictionaries (.stringsdict) with pluralisation handled as per CLDR 44

• i18next JSON v4

• Classic JSON (i.e. JSON files without any semantic syntax)

• Classic YAML (i.e. YAML files without any semantic syntax)

• Ruby on Rails (.yml)

We can build parsers for other standardised structures or your custom structures.

The connector’s parsers may include support for pluralisation syntax such as ICU, generating the required plural forms for each target language in accordance with specific versions of the CLDR.