A GitHub Action for translation sync

How it works

Three places hold configuration

Worth learning once, because the split is deliberate. Change the formatting in the app and every repo picks it up, including developers running the CLI locally. Change locamorph.yaml and only that repo changes.

Four modes, one input

Two need nothing but an API key. Two write back to GitHub and need a token. Which mode you pick matters less than the event you pair it with — that pairing is where first setups usually go wrong.

Never pair push with pull_request. That uploads source strings into your translation management system from a branch nobody has merged, leaving keys behind that no shipped code refers to. Use preview for that job — it shows the same information and writes nothing.

Built to fit the pipeline you already have

The four modes are building blocks, not a fixed route. Which ones you run, on which events, and what happens on either side of them are decisions you make in your own workflow file — so continuous localization ends up shaped like your process rather than someone else’s.

Every run sets outputs — has_changes, pr_url, pr_number, preview_output — and a later step can read them. Post the preview to Slack. Skip a deploy when nothing changed. Sit the sync between your existing build and test steps, behind a manual approval, or inside a matrix that syncs one locale per job. Run it in a monorepo with a different locamorph.yaml per package. None of that needs support from us; it is a workflow file doing what workflow files do.

A hosted integration decides when a sync happens and what the result looks like. Here both are yours, and changing your mind is an edit to a file you already own.

Setup

A secret and two files

About five minutes, most of it waiting for GitHub’s settings pages to load. The example repo has all four modes wired up if you’d rather read a working project than a code block.

1. Create an API key

   In your project settings, generate a key with the scopes the modes you plan to run need — see permissions below. API keys are available on every plan, including Free.

2. Store it as a repository secret

   Name it LOCAMORPH_API_KEY, so the workflows below work unchanged.

   gh secret set LOCAMORPH_API_KEY

3. Write a locamorph.yaml

   The CLI generates one interactively and commits nothing you didn’t confirm. Check the paths and languages it guessed before committing.

   npx @locamorph/cli init

   project_id: "your-project-uuid"
   translations_dir: ./locales
   format: json
   file_structure: "{LANG_ISO}.{FORMAT}"   # en.json, de.json, ...

4. Add a workflow

   Start with preview on pull_request. It changes nothing anywhere, so a wrong config costs you a red job and no cleanup. Add push on main once that goes green. Those two are the smallest continuous translation integration worth running.

5. Check it worked

   Open a pull request that touches a translation file. Within a minute the action comments with the strings that branch would add, update or remove. A green job and no comment means it found nothing to change. That is also a pass.

What’s supported

Formats, plans and quota

JSON and YAML today. Everything else locamorph handles goes through the web app and the REST API while CLI support is being finished.

The two directions behave differently while that lands: an upload skips those files with a “coming soon” notice, and a download warns and writes JSON into the configured paths anyway. Keep the unsupported formats out of locamorph.yaml for now — or tell us which one you need next.

Worth knowing before you set a cron to run every ten minutes. A preview writes nothing and adds no strings, but it still costs requests: ten languages across a few busy pull requests adds up faster than most people budget for.

Permissions

What each mode needs

pull and push barely touch GitHub. They read and write files in the checkout, so contents: read and an API key covers it. pull-request pushes a branch and opens a PR. preview writes a comment. Those two need a token.

When a run fails on a missing scope, the action names the exact permission in a GitHub error annotation and repeats it as a table in the job summary, rather than leaving you to hold a token’s permissions up against a docs page.

Common workflows

Two files cover most teams

Preview on pull requests, push on merges to main — both are in the tabs at the top of this page. Add the scheduled pull request when your translators work to their own rhythm rather than yours. The example repo has all four running against a real project.

What the preview comment looks like

Created once, then edited in place on every later push. A pull request that runs for a week ends up with one comment, not fourteen.

Most translation integrations give you two verbs, push and pull, so you learn what a merge did to your string catalogue afterwards — by going and looking at the catalogue. Preview inverts that: the diff shows up on the pull request while someone can still do something about it, and the run writes nothing to get it.

+ Menu.Projects
+ Menu.Collaborators
~ Common.Save

And what the pull request looks like

When translators finish, pull-request brings the files back as an ordinary PR. Same review, same approvals, same merge button as any other change to the repo.

@@ -12,6 +12,8 @@   "menu": {     "home": "Startseite",+    "projects": "Projekte",+    "collaborators": "Mitarbeiter",     "settings": "Einstellungen"   },

Related

Where to go next