How to continuously localize using GitHub Actions

How GitHub Actions help you create a seamless workflow

Lokalise’s GitHub app allows users to push and pull files between Lokalise and GitHub, and is used successfully by many of our customers. However, it has limitations:

• UI setup and UI-only access

You need to use Lokalise's UI to connect to GitHub and import resource files. The Lokalise auto-pull feature automatically imports modified/new keys from your resource files, but it does not remove deleted keys. This creates manual tasks in your otherwise seamless CI/CD workflows. The ideal situation would be to be able to push and sync your localization files directly from GitHub to Lokalise without adding deleted keys again. 

• Requests read/write access to entire repo

Lokalise requests read/write permissions to the entire connected repo. If you handle sensitive data related to finance and healthcare, for example, then granting read/write access is likely prohibited by your data-security requirements.

To avoid giving third-party access to your repositories, and initiate import/export of data directly from GitHub, you can use GitHub Actions with Lokalise.

How GitHub Actions works with Lokalise

First, what is GitHub Actions?

GitHub describes GitHub Actions as “...a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.”

All GitHub Actions are managed as workflows written in YAML files and each workflow can consist of multiple jobs. Read all about GitHub Actions in GitHub’s docs here. GitHub Actions can be triggered as CronJobs, manually, and automatically based on events that you define.

Workflow setup: Push, Pull, and Reset

You can manipulate any object or data in your Lokalise workspace that’s accessed using the Lokalise CLI or API with GitHub Actions. 

To show you how, I created a demo environment with GitHub Actions to localize a fictitious AI Tool. 

Demo environment: welcome to AI Emporium. 

View my repo here and use it to inspire your own GitHub Actions with Lokalise.

My workflow pushes new/modified translations to Lokalise, translates them with machine translation and then commits the updated machine translation on our main branch. This continuous localization process ensures that our translation updates are seamless and efficient.

Push sends your EN language resource file to your Lokalise project every time it is included in a commit on the main branch. All modified values replace pre-existing values, automations are run (Machine Translation in our example), and cleanup mode is used to remove keys that are not in the newly uploaded file.

Pull is triggered automatically after Push is completed. It downloads the German translations then commits those changes to main with a commit message of “Translations update”.

Reset cleans our demo environment. It is a CronJob that runs every day at 3:15 AM to delete branches in GitHub, then reset the main branch to a previous commit. After, it cleans the Lokalise project by uploading the reset en.json file to our Lokalise project.

Note: Our example GitHub Actions do not represent a real CI/CD customer use case in their current state. 

Our original PoC executed different push and pull actions from GitHub to Lokalise depending on the Git branch where the action was initiated. Our first iteration tagged keys with their GitHub branch name, did not overwrite modified values with machine translations, and created a pull request in our GitHub branch instead of committing directly to main.

You can view our branch dependent GitHub Actions in the v1.0.0 tag here.

10 GitHub Actions you can use with Lokalise

1. Instant Machine Translation for l10n testing

Once your app is internationalized, send extracted strings to Lokalise via GitHub Actions by manually running a push event that then triggers the pull of all the machine-translated resource files from Lokalise. Make modifications and run the push/pull again to see the changes.

2. Sharing localization files across teams and repositories

Imagine your product team is developing an app simultaneously for Android and iOS that will use the exact same key names and values. Your development team can regularly sync new and modified keys across resource files.

3. Vaulting over firewalls

Due to security policies, firewalls may block inbound connections to your repository. However, with GitHub Actions, every connection is outbound.

4. Scheduled synchronization of translated content

With GitHub Actions’ ability to run CronJobs you can run scheduled translation exports from Lokalise to GitHub and vice versa. What’s more, since Lokalise can include/exclude strings based on their translation statuses in exports, you can be intentional about which strings make it into your repo.

5. Automating Lokalise project snapshots

There are three options for auto-creating project snapshots in Lokalise: automatic daily, upon upload, and when executing some bulk actions. 

With GitHub Actions, you have more options and flexibility over when to create snapshots. You can use custom CronJobs or trigger an action that takes a snapshot whenever a different GitHub Action is initiated. 

6. Auto create localization tasks

Creation of translation tasks can be scheduled, run manually, or triggered automatically from GitHub Actions. For example, every Friday at 2PM, you can create a task to translate all of our unverified translations from the most recent file import.

7. Estimate translation pricing for translation Orders

For automatic order creation without paying minimum fees you can run a GitHub Action every few hours or days to create an order using the --dry-run option, which returns a price estimation. If the price returned for a language is 10, the Action ends. If the price totals for all languages are integers greater than 10 then place an order. 

8. Automated Version Control using Lokalise tags

In Lokalise you can use tags to differentiate branch-specific content. With GitHub Actions, tag the keys in a file sent from GitHub with the branch name where the file is committed. For detailed information on software localization workflows using tags, check out this guide. 

9. Send screenshots to Lokalise 

Context is key for UI translations. Since you can upload screenshots and link keys in Lokalise using the CLI, how can you use Actions to automate the process? You can have a workflow that monitors a folder where you store screenshots, and when a screenshot is added it automatically uploads the screenshot and uses the auto-detect feature to link with your keys. 

10. Check on task statuses

If your dev workflow depends on the completion of a task, tracking their progress will help you plan your sprint. For this, you can use an Action that lists all tasks and you can run it on demand from GitHub whenever you want to check on task statuses. You can check for tasks that are in-progress, completed, or both. Check out the example response in our dev hub here.

Conclusion

So there you have it. You now have a flexible, seamless, and secure method for transferring data between Lokalise and GitHub. 

The use cases above are just the tip of the iceberg of what is possible with GitHub Actions. As you explore the possibilities, feel free to share your own ideas so we can add them to the list.

Special thanks go out to Javier Martin Garay and Anil Kumar Krishnashetty for their work on this project.