Quickstart

Run init in your repositoryCopy Anchor Link

From the root of the repository, run:

npx transglot@latest init

init finds your locale files and works out the source language before anything leaves your machine. It prints what it found, for example Found messages/en.json JSON (nested), 412 strings, source language en, then prints a link and a code and opens the link in your browser.

Always run it as npx transglot@latest: in a repository that lists an older version of transglot as a dependency, plain npx transglot runs that older version.

If init reports No locale files were found in this folder., tell it where they are with --path and --format, for example --path messages/{locale}.json --format json_nested. If the repository only has the source file, name the languages to translate into with --targets fr,de.

Sign up or sign in, then approveCopy Anchor Link

The browser opens Connect the CLI. If you are not signed in, choose Sign in, or Sign up to create your account, and you come straight back to this page. A new account confirms its email address first; the page moves on by itself once you open the confirmation link.

Under Connect this terminal?, check that the code matches the one in your terminal, then select Approve. Approve only a code you started yourself. When the browser and the terminal are on different networks (an SSH session or a container, for example), the page then shows Type this number in your terminal: type the two digits into the terminal.

Create or choose a workspaceCopy Anchor Link

A workspace holds your projects and your team.

• If you have no workspace yet, the page shows Create your workspace. Enter a Workspace name and select Create workspace.
• If you have more than one, choose it under Choose a workspace.

If the workspace's account is on Free, the page offers a trial of the Starter plan with Start the free trial. Stripe asks for a card and nothing is charged that day. An account that cannot start a trial is offered the paid plan instead. Only the account's owners and billing members can start it; anyone else is told who to ask, and the terminal waits.

Create or choose the projectCopy Anchor Link

Under Choose the project for this repository, either connect an existing project, or check the name, Source language and Target languages that init proposed from your files and create the project.

Connecting creates a project token for this machine, so you need to be an admin of the workspace or an owner of its account. If you are not, the page names the admins who can connect it.

The page then says Your terminal is connected.

Run the first translationCopy Anchor Link

Back in the terminal, init writes transglot.json, uploads your source strings and any translations you already have, and shows what Glossa will translate, per language, with the number of words the run needs. Answer Start translating? to start it.

A progress bar runs for each language. When the run finishes, init writes the translated files next to your source file and prints the files to commit:

git add transglot.json .gitignore messages/
git commit -m "Set up transglot"

transglot.json is safe to commit: it holds no secret. The project token stays on this machine, outside the repository.

{
  "url": "https://api.transglot.ai",
  "sources": [{ "path": "messages/{locale}.json", "format": "json_nested" }],
  "pull": [{ "path": "messages/{locale}.json", "format": "json_nested", "locales": ["fr", "de"] }]
}

Review the translationsCopy Anchor Link

init ends with a Review translations link to the project. Open it to read and edit the translations in the editor. Translations that need a human are flagged for review; see Translation states.

Push and pull as you workCopy Anchor Link

When you add or change source strings, push them and wait for the translation, then pull the results:

npx transglot@latest push --wait
npx transglot@latest pull

push uploads the files named under sources. New and changed strings are translated automatically while the project's Auto-translate setting is on, which it is by default. --wait waits for that translation to finish. pull writes the files named under pull.

In the folder init set up, these commands use the token stored on this machine. In CI, create a deploy token and store it as the TRANSGLOT_TOKEN secret instead; see Continuous integration or use the GitHub Action.