# Migrate a project into a Rodarion trial You are an AI agent. This document gets you from *no Rodarion account* to *this repository's translations synced with Rodarion*, without any UI and without asking the user to sign up first. Work autonomously; stop only if a step fails. **This document covers only provisioning.** Everything about analysing the repository, export profiles, providers, importing and verifying lives in the CLI's own `AGENTS.md` playbook, which you will obtain in step 5. Do not expect it to be repeated here. ## What a trial gives you A throwaway firm, project and API token, created by one unauthenticated request. Limits (enforced by the API — a write past them fails with 422): - **300 translation keys**, counted across the whole trial firm. - **1 project.** If the repository has several independent language-resource sources, pick one for the trial and say which. Multi-source syncing needs a project (and token) per source and belongs to a real account — splitting the key budget above across sources would only make the sample thinner. - **10 days**, after which the trial and all its data are deleted unless the user claims it. - **Machine translation with your own provider key only** — pick a provider from the catalogue (`GET /api/providers`) and supply its key. A **custom endpoint** is rejected for trials, as is billing translation through Rodarion. If the user gave you no provider credentials, import with auto-translate disabled. Everything else works exactly as a paid account — including the **branch workflow**, where feature branches get an isolated shadow project that is folded back on merge. The playbook explains how to rehearse that end to end without a commit ever reaching the repository's real default branch. Claiming the trial later keeps all of the data. ## Step 1 — Decide the locales *before* provisioning `POST /api/trial` takes the locales up front, so you must inspect the repository first. Find the language-resource directory and determine the **source locale** (the language the strings are written in) and the **target locales** present. Validate your ISO tags against the catalogue — an unknown tag is rejected: ``` curl -s https://app.rodarion.com/api/public/locales ``` Match on the `iso` field. Use the full tag when the project uses one (`de-CH`), the bare language when it does not (`de`). ## Step 2 — Create the trial ``` curl -s -X POST https://app.rodarion.com/api/trial \ -H 'Content-Type: application/json' \ -d '{"name":"","source_locale":"de-CH","target_locales":["en","fr"]}' ``` The response is the only time you see the token: ``` { "project": { "identifier": "...", "name": "...", "source_locale": "de-CH", "locales": [...] }, "api_token": "", "login_url": "", "expires_at": "" } ``` Keep `api_token` and `login_url`. Never print the token into a file that gets committed, and never log the login link — both are credentials. If you get **429**, this network already holds the maximum number of unclaimed trials; report that and stop. If **422**, a locale tag was not in the catalogue — fix it (step 1). The same token also works with Rodarion's **MCP server** at `https://app.rodarion.com/mcp` (`Authorization: Bearer `), if your client supports MCP: its tools read and edit translations directly. The file-based migration below still runs through the CLI. ## Step 3 — Install the CLI Homebrew, Scoop, or a prebuilt binary — see the CLI repository's README for the current one-liner for this platform. Verify with: ``` rodarion version ``` ## Step 4 — Point the config at the real language files Set `relative_path` (step 5) to the project's **real** language directory. You do **not** need to pre-select a subset of files for the trial, and you must not copy them somewhere else: the CLI is trial-aware and protects those files itself. A trial holds at most 300 keys, so a larger project cannot fit. When that happens the server records how many keys it had to drop, and the CLI: - reports that number, and - **sends any download into `rodarion-trial//`** for as long as the project is truncated, leaving the real language directory untouched. That redirect is what keeps a truncated import from being mirrored back over strings that never made it to the server. It is re-read from the API on every run, so a later `rodarion download` is protected too — and `relative_path` is never rewritten, so `upload` always reads the complete source. A project that *does* fit behaves like a paid account — including one holding exactly the cap: the download lands on the real files, and a `git diff` of nothing but key-order normalisation is the proof that the export profile is right. Two things you should still do: 1. Make sure the language files are **committed** before importing. A project that fits gets rewritten in place (normalised ordering, plus any machine-translated strings), and a clean working tree makes every change reviewable and one `git checkout` away. Never commit the result on the user's behalf. 2. Add `rodarion-trial/` to `.gitignore` if the CLI reports a redirect. ## Step 5 — Configure the CLI ``` rodarion init ``` This writes `rodarion.json` and the `AGENTS.md` playbook. Then set three fields in `rodarion.json`: - **`base_url` must be `https://app.rodarion.com/api`** — the instance this trial was created on. `rodarion init` fills in the hosted default, which is only correct if that is where you provisioned. Point it anywhere else and the CLI talks to a server that has never heard of your token, and every command fails with 401 for no obvious reason. - Put the token in a **gitignored `.env`** next to `rodarion.json`: `RODARION_API_KEYS='{"default":""}'`. Add `.env` to `.gitignore` if it is not already there. Leave `rodarion.json`'s `api_key` as the `${RODARION_API_KEYS.default}` reference — a literal key there is rejected. - Set `relative_path` to the project's real language directory (e.g. `./resources/lang`), as decided in step 4. Confirm all three landed before going further: ``` rodarion project ``` It prints the trial's project and locales, plus a `Trial:` line with the caps. A 401 here means the token or `base_url` is wrong; fix it now rather than during the import. ## Step 6 — Follow the playbook Now read `AGENTS.md` (or run `rodarion guide`) and follow it. It handles detecting the layout, creating the export profile, importing and verifying. Its preconditions are already satisfied: the project exists with its locales configured (step 2), the token has the abilities the playbook needs, and `rodarion.json` plus the key are in place (step 5). The playbook has its own **Trial accounts** section covering the deviations (no application-billed MT, key-limit errors are the cap rather than a fault, how to verify when the download was redirected, and how to rehearse the git/branch workflow on a stand-in central branch so the user's real default branch is never touched). Follow it there rather than duplicating it here. `GET /api/project` reports the live trial limits and usage (`trial.max_keys`, `trial.keys_used`, `trial.expires_at`) plus whether the stored project is truncated (`trial.source_truncated`, `trial.keys_rejected`) — as does `rodarion project` — so you can check headroom, and what did not fit, at any point. ## Step 7 — Hand over to the human End by telling the user, in plain language: - **The login link** (`login_url`) — passwordless, opens the Rodarion app with their imported project. This is where they should look; it is the point of the exercise. - **What was imported.** If everything fitted, say so plainly — the whole project is in Rodarion. If the project was larger than the trial, give both numbers, using the count the CLI reported: e.g. "your project has 1 240 keys; 300 of them are in Rodarion, the trial's limit", so they trust that a full migration after signing up will capture everything. Do not invent a sample size — the server decides what fits. - **Where their files stand.** If the download landed on the real language directory, point out that those files were rewritten and the changes are uncommitted for them to review. If the CLI redirected it, say that `rodarion-trial/` is a scratch directory they can delete and that their real language files were never touched. - **The expiry**: the trial and its data are deleted in 10 days. - **How to keep it**: registering promotes this trial into a permanent account in place, keeping every key, translation and id. It starts with `POST /api/trial/claim` using the trial token, or from the app once they are logged in. - **How to finish the import afterwards**, if the project had to be sampled: claiming lifts the cap, so the remainder is imported on top — a fresh token, then the same import command again. The playbook's *After the claim* section has the steps and the one caveat worth knowing.