Migrating from Crowdin

Your translations, translation memory and glossary are years of work. Moving them should not be a week of exports, spreadsheets and re-imports.

npx @textsetu/cli@latest migrate crowdin --from 123456 --dry-run
npx @textsetu/cli@latest migrate crowdin --from 123456

One command reads a Crowdin project through Crowdin’s API and writes it into a TextSetu project. It runs on your machine with your own Crowdin token, so no third-party credential is ever stored by TextSetu, and nothing in Crowdin is modified — the migration only reads.

Run --dry-run first, always. It reads both sides in full and prints exactly what would land: which languages get added, how many keys and TM segments and glossary terms, every key that had to be renamed, and every loss as a number. It writes nothing and exits 0.

What moves


Strings and translations	Every language at once, with plurals keeping all their CLDR forms and placeholders (`%s`, `%1$d`, `{count}`) byte-identical.
Key context	Crowdin’s string context becomes the TextSetu key description.
Labels	Become tags on the key.
Translation memory	Every segment and all of its language variants, with region subtags like `pt-BR` and `pt-PT` kept distinct.
Glossary	Terms with their status, part of speech, term type, definition, notes and grammatical gender.

Before you start

In Crowdin, create a personal access token under Account Settings → API. It only needs read access. Note your project id — the number in the project URL. On Crowdin Enterprise, note your organization name too, the <name> in <name>.crowdin.com. In TextSetu:

Create the project you are migrating into, and set its source language to match Crowdin’s. The command adds Crowdin’s source language if it is missing, but it cannot make it the project’s source — do that first, or your source strings arrive as just another target language.
Sign in with textsetu login. A personal access token is required for the translation memory and glossary, because both belong to the organization; a project token can still do --only translations.
Check your plan has head-room. Keys, languages, translation memories and glossaries are all metered. An organization over its limits is read-only, and the run stops.

Decide your key shape before you run. A Crowdin identifier is unique per file; a TextSetu key is unique per project. If common.json and errors.json both contain title, those are two Crowdin strings competing for one TextSetu key. The migration refuses and names them rather than silently letting one win. Either rename one in Crowdin, or run with --on-collision prefix, which namespaces every key by its file (common.title, errors.title).

Migrating

Set your tokens. export CROWDIN_TOKEN=… for Crowdin (prefer the environment variable over the --crowdin-token flag, which leaves the secret in your shell history), and textsetu login for TextSetu.
Dry-run, and read the plan. Section Reading the plan explains every line.
Resolve anything it surfaced — a key collision, a language spelled differently in the two tools (--locale-map zh-CN=zh-Hans), renames you would rather make yourself in Crowdin. Then dry-run again.
Run it for real. Languages are created first, then translations, then the translation memory, then the glossary.
Verify. textsetu status shows completeness per language — compare it with Crowdin’s own. Then spot-check a plural key, a pt-BR/pt-PT pair and a string with placeholders.

Choosing what to bring

Flag
`--from <id>`	The Crowdin project. Prompts at a terminal when omitted.
`--crowdin-tm <id>` / `--crowdin-glossary <id>`	Which TM and glossary to bring. Prompts at a terminal; otherwise lists the options.
`--only <part…>`	Any of `translations`, `tm`, `glossary`. Default: all three.
`--organization <name>`	Crowdin Enterprise.
`--locale-map <from=to…>`	Map a Crowdin language onto a different TextSetu code. Repeatable.
`--on-collision prefix`	Namespace every key by its Crowdin file.
`--dry-run`	Print the plan and write nothing.
`--json`	The same plan as a document, including the full rename list.

Reading the plan

crowdin  textsetu  action
───────  ────────  ─────────────
en       en        source exists
fr       fr        add
zh-CN    zh-Hans   add (--locale-map)

translations        10 key(s), 1 plural · 1 request(s), 2 KB
                    3 key(s) get a description or tags
                    ⚠ 10 identifiers renamed to a valid key
                    ⚠ 1 deliberately-empty translation(s) will arrive untranslated
                    1 max-length limit(s) noted in the key description
translation memory  "Product TM" → new TM · 4 entries · 7 language(s) · 1 request(s)
glossary            "Product Glossary" → new glossary · 3 term(s) · 3 language(s)

Dry run: nothing written. 18 TextSetu request(s).

Line	Meaning
`source`	Crowdin’s source language.
`add` / `exists`	Whether the language will be added to your TextSetu project.
`(--locale-map)`	This mapping came from your override, not from normalization.
`N key(s), M plural`	Keys to import, and how many carry plural forms.
`N request(s), N KB`	How the upload is split against the 10 MB request limit. One request is the normal case.
`N key(s) get a description or tags`	Metadata only ever fills what is empty, so a second run usually shows `0`.
`→ new TM` / `→ existing "…"`	Whether a container is created, or reused by name.

Warnings

Warnings never stop a run. Each names a loss, with a count, so you can decide before anything is written.

Warning	What it means	What to do
`N identifier(s) renamed to a valid key`	A TextSetu key segment allows letters, digits, `_` and `-`, so `user profile` becomes `user_profile`. `--on-collision prefix` counts as a rename too.	Nothing, or rename in Crowdin first. `--json` lists every pair.
`N deliberately-empty translation(s) will arrive untranslated`	Crowdin can hold an empty string as a real translation; TextSetu treats empty as absent.	Accept it, or give those strings a real value.
`N max-length limit(s) noted in the key description`	TextSetu has no max-length field, so Crowdin’s limit is appended to the description as text.	Nothing. It is informational.
`N segment(s) have no source-language text and are skipped`	A TM segment with no variant in the source language has no lookup key.	Check the TM’s source language matches the project’s.
`N extra synonym(s) dropped`	Crowdin allows several terms per language in one concept; TextSetu keeps one.	Nothing, or split the concept in Crowdin.
`N concept(s) have no source-language term and are skipped`	The same, for glossary concepts.	Check the glossary’s source language.
`The TextSetu project has no <lang> language…`	Your project’s source language differs from Crowdin’s.	Set the source language in project settings, then re-run.
`The TextSetu project requires approval…`	Imported values land as proposals, not live translations.	Approve in bulk afterwards, switch approval off for the migration, or migrate with a token that can approve.
`The glossary exceeds 10 MB in one request`	The glossary import is a single request, and this one is too big.	Split the glossary in Crowdin and migrate the halves.

When something fails

A migration is several write phases, and it is deliberately not a transaction. If one fails, the command says what already landed:

error Migration failed during translation memory: Your organization is over its
plan limits and is read-only. (LIMIT_001)
  Already applied, and NOT rolled back: 8 language(s), 10 key(s), 10 description/tag update(s).
Re-run the same command: every step is idempotent, so what already landed is not duplicated.

Fix the cause, then run the same command again.

Re-running is always safe, and is both the recovery path and the ordinary one. Imports update rather than duplicate, a language that already exists is skipped, a TM or glossary already carrying the Crowdin one’s name is reused, and descriptions and tags are only ever filled — so an edit you made in TextSetu in between survives the next run. There is no state file to clean up.

Common causes:

Message	What to do
`No Crowdin token.`	Set `CROWDIN_TOKEN`.
`Crowdin rejected the token (401).`	Expired or revoked — or an Enterprise token used without `--organization`.
`Migrating a translation memory or glossary needs a personal access token`	You are using a project token. Run `textsetu login`, or pass `--only translations`.
`N TextSetu key(s) would be claimed by more than one Crowdin string`	Two files share an identifier. Use `--on-collision prefix`, or rename in Crowdin.
`Several Crowdin languages map onto the same TextSetu code`	Separate them with `--locale-map`.
`TextSetu language codes are at most 10 characters`	Map the long tag to a shorter code with `--locale-map`.
`Your organization is over its plan limits and is read-only. (LIMIT_001)`	Remove resources or upgrade, then re-run. Nothing already written is lost.
`Crowdin … (403)` / `(404)`	The token’s owner cannot read that project, TM or glossary, or the id is wrong.

To undo rather than repeat: every phase is recorded as a job in the import history, and each can be reverted from the UI. The migration never deletes anything.

What does not move

A migration is judged on what did not arrive, so each of these is a counted line in --dry-run rather than a surprise afterwards.

Approval state. Everything arrives as a value, or as a proposal on a project that requires approval. Crowdin’s approved/unapproved distinction is not carried.
History, authors, timestamps and comments. Only the current translation moves.
Deliberately-empty translations, which arrive as untranslated.
File and directory structure. Crowdin’s files become key namespaces under --on-collision prefix, and are otherwise discarded. If your file tree is the thing you want to keep, crowdin download followed by textsetu init and textsetu push --translations preserves it instead.
Screenshots. TextSetu stores one screenshot per key with no regions, so Crowdin’s many-to-many mapping with bounding boxes has nowhere to land.
maxLength, folded into the key description.
Glossary synonyms beyond the first per language.
A TM source text’s leading and trailing whitespace. The source is the TM’s lookup key and is stored trimmed. Translations keep theirs, and so do all ordinary translation values.
Project settings — QA checks, workflow steps, plural-rule overrides. Configure the TextSetu project first.

Large projects

Translations upload as one multi-language document, split only when they would exceed the 10 MB request limit. The translation memory is chunked at 500 segments per request. Writes are paced under the API’s rate limit, and Crowdin reads run six at a time against its 20-concurrent cap. A project of a few thousand keys takes a minute or two; if a run is interrupted, re-running it costs only the reads.

Next steps

Moving your file sync too? The CLI guide maps crowdin.yml onto textsetu.json field by field, including the placeholder and languages_mapping equivalents.

Import & Export — for anything the migration deliberately leaves out.
Translation Memory and Glossary — what those assets do once they arrive.
Approval workflow — if your values landed as proposals.

Start here

User guides

Reference

Migrating from Crowdin

What moves

Before you start

Migrating

Choosing what to bring

Reading the plan

Warnings

When something fails

What does not move

Large projects

Next steps

​What moves

​Before you start

​Migrating

​Choosing what to bring

​Reading the plan

​Warnings

​When something fails

​What does not move

​Large projects

​Next steps

What moves

Before you start

Migrating

Choosing what to bring

Reading the plan

Warnings

When something fails

What does not move

Large projects

Next steps