The command line tool
Install the transglot CLI, connect a repository to a project in one command, and push and pull locale files from your terminal or CI.
The command line tool is the npm package transglot. It reads a transglot.json file in your repository, uploads your source strings to a project, and writes the translations back into your locale files. It has no runtime dependencies.
Requirements
- Node.js 22 or later. On an older version the CLI stops before doing anything and prints
transglot needs Node.js 22 or later.followed by the version it found. - A plan with API access. The CLI, the API and the GitHub Action start on the Starter plan. See pricing.
- An admin to approve the connection. Connecting a repository creates a project token, so the login that approves it in the browser must be an admin of the workspace or an owner of its account.
Install
You can run the CLI without installing it, install it globally, or add it to your project.
npx transglot@latest initRun it as npx transglot@latest rather than npx transglot. In a repository that lists an older transglot as a development dependency, npx runs that older version unless you ask for @latest.
Check the installed version with transglot --version.
Set up a repository
init connects a repository to a project, writes transglot.json, and runs the first translation. Run it in the root of your repository, on a machine with a browser.
Scan the repository
npx transglot@latest initinit finds your locale files and works out the source language. Nothing is sent to transglot yet. If it cannot tell which files are your locale files, pass the layout with --path, for example --path messages/{locale}.json.
Sign in through the browser
The terminal prints a link and a code such as WDJB-MJHT, and opens the link. The page is titled Connect the CLI. Sign in or sign up there.
Under Connect this terminal?, check that the page shows the same code as your terminal, then select Approve. Approve only a request you started yourself; otherwise select Decline.
When your browser and the terminal reach transglot from different networks (SSH, a container, a VPN that covers only one of them), the page shows Type this number in your terminal. Type the two digits into the terminal, or pass them as --confirm.
Choose the workspace and project
If you have no workspace yet, the page asks you to name one under Create your workspace. If the workspace's account is on the Free plan, its owners and billing members are offered Start the free trial (or a paid plan when the account cannot have a trial) before they continue. Other members are told who can change the plan.
Under Choose the project for this repository, connect an existing project or create the one the terminal proposed from your files. The page then says Your terminal is connected.
Upload and translate
Back in the terminal, init writes transglot.json, uploads your source strings and the translations you already have, shows how many words the first translation needs, and asks once before it starts. It then translates and writes the finished files into your repository.
A file that holds strings the server does not have is kept, and the terminal says which and why.
Commit transglot.json. init lists the files to commit when it finishes.
If the repository already has a transglot.json, init only signs you in and links the folder on this machine. It does not change the file and uploads nothing, so an old branch never replaces your team's source text. Pass --force to scan the repository again and rewrite the file.
Where the token is kept
Approving in the browser creates an ordinary project token with the push and pull abilities, named after your machine. It appears with the project's other tokens under Settings → Developer, where deleting it disconnects the terminal. See Deploy tokens.
The CLI keeps the token in credentials.json, in the first of these folders that applies:
TRANSGLOT_CONFIG_DIR, when it is set (it must be an absolute path).$XDG_CONFIG_HOME/transglot, whenXDG_CONFIG_HOMEis an absolute path.%LOCALAPPDATA%\transgloton Windows.~/.config/transglototherwise.
On macOS and Linux only your user can read the file. A token is only ever sent to the server it was created for.
init also writes .transglot/project.json in the repository and adds .transglot/ to .gitignore. That file links the folder to the token on this machine only, so a copy of the folder on another machine selects nothing. In a linked folder, push, pull and status use the stored token without any setup.
Everyday commands
npx transglot@latest push --wait # upload source strings, wait for the translations
npx transglot@latest pull # write translations into your locale files
npx transglot@latest status # the project and its active runspush returns as soon as a translation run is queued, so use push --wait before pull. See the command reference for every command and flag.
In CI
In CI there is no browser sign-in. Create a deploy token, store it as the TRANSGLOT_TOKEN secret, and the CLI uses it. While TRANSGLOT_TOKEN is set it always wins over a token stored on the machine, and the CLI never opens a browser. See Use the CLI in CI and The GitHub Action.
Troubleshooting
Run the command in your terminal again for a new code.
The request was declined, or the terminal typed the wrong number twice. Run the command again for a new code.
Connecting the CLI creates a project token, which needs an admin of the workspace. The page names the admins who can; ask one of them to connect the repository, or to create a deploy token for you.
The CLI detected a CI environment. Store a deploy token as the TRANSGLOT_TOKEN secret instead. See Use the CLI in CI.
This folder is not linked on this machine and no token is in the environment. Run npx transglot@latest init to sign in and link it, or export a deploy token as TRANSGLOT_TOKEN.