Concepts

easyi18n keeps the translations of a software product in one place and ships them to that product. This page names the things you meet in the dashboard and says how they relate: workspaces and projects, keys and content, source and target languages, the states a translation goes through, versions and publishing, AI credits, and roles. Getting started walks through the first project; this page is the vocabulary behind it.

Workspaces and projects

A workspace is the unit that pays. It owns the plan, the AI credit balance, the members and the projects. Every account gets a personal workspace when it signs up, and a paid plan lets you create more. A workspace has a handle, the @acme part of a project address such as @acme/mobile-app; the handle is unique across easyi18n and you claim it during onboarding.

A project holds the strings and documents of one product, together with their translations, languages, glossary, AI settings and output formats. A project belongs to exactly one workspace and has a slug that is fixed once created. Members of the workspace reach its projects without a second invite.

Plans cap what a workspace can hold rather than what it can do: the Free plan limits projects per workspace, keys and documents per project and API keys per project, and the paid plans lift those caps and add features such as custom Content steps, source review and delivery domains. The current limits and prices are in the workspace settings under Plan & Credits. When a workspace drops to Free with more projects than the plan allows, nothing is deleted: the most recently updated or published projects stay editable, up to the plan's limit, and the rest become read-only until the plan is raised again or enough projects are deleted.

Source language and target languages

Each project has one base language, the language you write in. You pick it first when you create the project, and every other language you add is a target language that receives translations. Languages come from the open BCP-47 catalog, so pt-BR, zh-Hant or es-419 are accepted alongside plain es; a code is checked against the CLDR tables, and a subtag that is not a real language, script or region is refused when you add it.

A target language has a fill mode. In the default mode the AI engine translates it. In manual mode the dashboard shows the language as "Manual language — AI runs skip it": every AI run leaves it alone and a person, or a tool of your own, supplies the text. Import, export and publishing treat a manual language like any other.

Changing a source string does not rewrite its translations at that moment. Each translation remembers which source it was made against, and the dashboard derives from that comparison whether it is still current. The next AI run re-translates the values nobody has reviewed or confirmed, which spends credits, and leaves the rest alone. The rules are in the states section below.

Keys and content

A project has two kinds of material, called dimensions in the dashboard.

Keys are the short strings an application looks up by name: button labels, error messages, titles. A key has one source value, one translation per target language, and metadata that helps translate it: a description, tags, screenshots, a maximum length, the placeholders it must keep, and whether it is a plural, Markdown or inline HTML. A key can be switched off: a disabled key stays in the project but is left out of published output and of AI runs. Keys leave easyi18n as localization files in the formats you enable, two per project at most, or through the Flutter runtime SDK. Keys editor covers the list and the editor of a key.

Content is for documents: a page, an article, a help text. A document is Markdown, HTML or plain text, declared once and never converted. easyi18n splits it into blocks (headings, paragraphs, list items, code, tables and the like), and the block is the unit it translates, tracks and re-translates when the source changes. A document is translated by a pipeline, an ordered list of steps whose first step is always Translate; paid plans can add their own prompt steps. Content shares the project's context, tone and glossary with Keys. Published documents are read through the authenticated API, never from the public delivery network that serves key bundles. Documents covers adding and editing them, and Pipelines the steps a translation runs.

The WordPress plugin uses both: the strings of the theme and plugins are keys, and each post or page is a document.

States of a translation

A key translation has one ladder and several independent marks. The ladder says how far a person has signed off on the text; the marks record facts around it. None of them is overwritten by another.

The ladder has three rungs, and a translation is always on exactly one:

Rung	Meaning	How a translation gets there
Translated	Has a value, no human signature	An AI run, an import, or a signature being withdrawn
Reviewed	A person read the value and signed it	Saving a value by hand, or the review action
Approved	Final sign-off	The approve action

"Untranslated" is not a rung: it is the absence of a value. Deleting a translation is the only way back to it, and the only destructive action on a translation. A reviewed or approved value is pinned: an AI run replaces it only when you start a re-translation and choose Replace all, and a plural that is missing forms gets them filled in and loses its review status. Otherwise only a person can withdraw the signature, which returns the value to Translated without touching the text. Review is optional. A Translated value publishes and ships like any other unless a publish asks for approved values only.

Where a value came from is recorded separately from the ladder: a person, the AI engine together with the model that produced it, or a file import. An AI-written value that someone approves keeps its origin.

The marks sit beside the ladder:

• Source confirmation is derived, not stored. The dashboard compares the source a person last confirmed against the live source. A translation nobody has confirmed shows "Unconfirmed"; one confirmed against an older source is stale, and the editor shows the source diff. Saving, reviewing or approving confirms; Still valid confirms without changing the text, for the case where a typo fix in the source left the translation correct. A stale approval still publishes; the mark queues it for a look, it does not unpublish anything.
• Review requested is set by a person with Request review and cleared only by a person. It survives edits and coexists with any rung: "Approved, review requested" is a valid state.
• Incomplete marks a plural that lacks one of the forms its language defines. As long as the other form is there it still publishes, and the missing count falls back to other; a plural without other is refused at publish.
• Blocked marks a value the AI engine gave up on after its retries for the current source and model; a new source or model, or your own edit, lifts it.

Switching a key off is a property of the key, not of a translation, and it is the only switch that keeps a key out of publishing. Review and statuses shows where each state appears in the dashboard and how to sign translations one by one or in bulk.

States of a document

Content follows the same ideas at a different grain: the document signs, the block records facts. For each target language a document has a signature (Reviewed or Approved, or none) and the same Still valid confirmation and Request review mark as a key. Signing needs the language to be complete and no run in progress. Editing a block by hand marks it "Edited", pins it against future runs, and clears the document's signature, since the signature vouched for different text.

Each block records whether it is untranslated, translated against the current source, stale against an older source, or failed in the last run, plus one human mark: Flag this block, for a paragraph that needs another look. Flags are a note, not a lock: they do not change what a run does. The document list also shows a pipeline status per language, from untranslated through running, partial and done to failed or stale, which describes the last run rather than anyone's judgment. Runs and review covers starting runs and signing a language.

Versions and publishing

Editing changes the project's working state. Your application sees none of it until you publish, which freezes the working state into an immutable version named YYYY.MM.DD.N: the UTC date and a counter that starts at 1 each day, so two publishes on one day are distinct and comparable at a glance. Versions are kept for the last five days that had a publish, up to thirty per day, and the version currently served is never pruned. Restore does not rewind the project: it copies an older version into a new one, labelled with its origin, and leaves the working state untouched.

Publishing asks two questions about translations that are not ready:

• What to do with an incomplete translation. Skip leaves it out of the version, which lets your own tooling detect the gap. Source fallback serves the base-language text in its place. Content adds Hold, which keeps serving the previously published document for that language.
• Whether only approved translations count as complete. Off by default; when on, an unapproved value follows the choice above. It does not wait for anyone and does not block the version. A workspace can also require approval for every publish of its projects: the owner turns on Require approval before publishing in the workspace settings, on a plan that allows it.

Disabled keys are left out of every version. A publish reports what it left out, so a version can succeed with gaps you then fix and publish again.

Published keys reach your application in one of two ways. As files, through Export in the dashboard or the CLI's pull, which read the latest published version through the authenticated API. Or as runtime bundles, which the Flutter SDK fetches from a public delivery network and hot-swaps without a release; those bundles carry no authentication, by design, because translations are not secrets. Content publishes per document, each document keeping its own served version, and is read only through the authenticated API. Publish a version covers the Keys publish panel and restoring a version, Delivery the runtime bundles and custom domains, and Publish and versions the Content publish panel and restoring a document.

AI credits

AI work is paid in credits, a workspace balance shared by its projects. One credit is a fixed 0.005 US dollars of model cost, and operations are charged after they run, on the tokens the model reported, so a cost shown beforehand is an estimate. A Content run asks for confirmation when its estimate passes the warning threshold set for the project. Each charge is listed with its model and token counts under Usage in the workspace settings.

Two kinds of credits live in the balance. Monthly credits come with the plan, refill each month and expire if unused. Top-up credits come from credit packs, never expire and survive a change of plan. A trial gives the plan's features with the Free allowance of monthly credits. The workspace owner can set a monthly spending cap; when consumption reaches it, AI operations stop until the month resets or the cap is raised. Billing and credits covers the plan, the credit packs, the cap and the usage list.

Translate with AI covers the runs on keys and the model that translates.

What spends credits: AI translation runs on keys and documents, re-translation, AI import from a screenshot or pasted text, the improve and rewrite helpers, source review, and the assistant that refines your instructions. What does not: editing by hand, reviewing and approving, publishing, exporting, CLI pull and doctor, and file import in a format easyi18n parses itself.

Roles

Membership is managed at the workspace level. Three roles exist:

Role	Can
Owner	Everything, including billing, the spending cap and deleting the workspace. One per workspace
Admin	Manage members and projects, publish. No billing, cannot delete the workspace
Member	Work in projects. Can be limited to a chosen subset of the workspace's projects

Owners and admins always reach every project; plans cap how many administrators a workspace has, and members are not capped. Invitations go out by email as admin or member. Members and roles covers inviting, changing roles and limiting a member to some projects.

Each project derives its own membership from the workspace. An owner or admin of the workspace becomes an editor who can publish in every project; a member becomes an editor who cannot publish; the person who created the project keeps the project owner role. Editors create and edit keys, documents and translations, and review, approve and confirm them. Publishing and restoring a version need the project owner or an editor with publishing rights.

A deleted project can be restored for thirty days from Deleted projects in the workspace settings; after that it is deleted for good, with everything in it. Deleting a key or a document takes it out of the project and of the versions published afterwards. Trash covers both.