Getting started

Create a project, add your source strings, review translations, and publish a version for your app to consume. This guide covers the Keys workflow for application strings. The terms it uses, from workspaces to versions and credits, are defined in Concepts.

Create your workspace and project

1. Open the easyi18n app and sign in or create an account.
2. Create a workspace, or choose one you already belong to. A workspace groups projects and shares its plan and credit balance.
3. Name your project. Check the address preview before continuing: the project slug is fixed once created. For an address ending in @acme/mobile-app, acme is the workspace handle and mobile-app is the project slug.
4. Add languages. Your first selection is the base language of your source text; the remaining selections are translation targets. Search by name or locale code, such as es or pt-BR.
5. Optionally describe your product, audience, and terminology in the context step, then set a tone. You can skip these and edit them in project settings.

Choose how your app receives translations

Your application	Integration	Next step
Already uses localization files, such as Flutter ARB or Xcode String Catalogs	Mode A: manage translations in easyi18n and keep your app's existing localization system.	Import your files, then export or use the CLI to download a published version.
Uses the Flutter easyi18n runtime SDK with context.tr()	Mode B: the SDK reads published translations and can update them at runtime.	Initialize the SDK integration and push strings from Dart source with the CLI.

Set the integration mode in project Settings → General. It determines the suggested handling of incomplete translations when you publish. The CLI's mode: in easyi18n.yaml is a separate setting; changing it does not update the dashboard setting.

For file delivery, open Settings → Output, choose the formats your app uses, and save. You can enable up to two formats. Importing a file and enabling an output format are separate steps. Enabling a format does not publish a version.

See the CLI guide for Flutter ARB, Xcode .xcstrings, and runtime SDK setup, including which features require CLI 0.12.0.

A WordPress site needs neither a file format nor the CLI. The WordPress plugin sends the site's strings and posts to the project and serves what you publish.

Add source strings

For a first string, open Keys, select Add key, enter its base-language text, and save. For example, a key named welcome might contain Welcome {name}. Keep placeholders such as {name} in the translations so your app can substitute the value.

To bring in existing translations:

1. Open Import → Import a file in your project.
2. Drop a file on its language card, or select the card to browse. Start with the base-language file so the project has the keys that target files refer to.
3. Check the detected entries and any warnings. If a file requires AI parsing, review the proposed keys or translations before accepting them.
4. Run the import and read its result, including skipped or failed entries.

Import creates new keys and can overwrite existing values. It preserves human-edited source text and protected translations, reporting those conflicts as kept values. Check the selected files before starting, then read the report to see which values changed or were kept. Import keys covers the formats, the report and the files that need AI.

A String Catalog can contain several languages. Import it on the base-language card to create its keys; a target-language import needs translations for that language in the catalog. For a repeatable upload/translate/download loop, use CLI sync.

Extract keys with AI is another import option for screenshots or loose text. It uses credits. Developers using tr() calls can instead use CLI extract to inspect source strings offline and push to register them.

Translate and review

Open a key to edit its translations. Languages configured for manual translation are left for you to fill; AI translation uses workspace credits. Check the selected languages and the cost shown for an AI operation before starting it.

Review the wording, placeholders, and any plural forms. Mark reviewed translations approved if you want publication to count only approved values. Saving a translation changes the project's working state. Your application's published version stays the same until you publish again.

Publish a version

Open Publish from the project's Keys view. The panel covers every key in the project, even if you have a search or filter active. Check the coverage summary and choose how incomplete translations should be handled:

• Skip leaves missing translations out of the snapshot. Use this for file integrations where your own tooling needs to detect untranslated entries.
• Source fallback serves the base-language text for missing translations. This is the default for a runtime SDK project.

Only approved translations count as complete makes unapproved values follow that same choice. It does not wait for approval or block the entire version. If the project has no integration mode, choose an incomplete-translation option before proceeding. Configure an output format if the panel asks for one.

Select Proceed to create a published snapshot. Read any validation warnings: publication can succeed with values left out. Fix those values and publish again. An export-name collision blocks publication and must be resolved first. Publish a version covers the panel, the list of versions and restoring one.

Use the published translations

For a manual download, open Languages → Export, select a language and an enabled output format, then export. The download reads the latest published version, so publish again after editing a translation that you want in the file. Export keys covers the screen and what the file holds.

For a file-based build, use CLI pull, then run your framework's normal localization build step. Flutter ARB projects run flutter gen-l10n after pulling. Xcode projects can use sync to upload and translate their catalog, then publish and merge the result back into that same file.

For a runtime SDK integration, use the Flutter SDK page to mount Easyi18nScope and load published translations. Keep API keys in developer or CI environments; they do not belong in client application code.

If the result is not what you expected

Symptom	Check
A download contains the old wording	Publish the working changes, then download again.
Export has no formats to choose	Enable a format in Settings → Output and save.
An imported target file has no matching keys	Import the base-language keys first.
AI leaves a language untranslated	Check its fill mode, available credits, and the operation's reported failures.
A CLI request is refused	Check the configured project, API key scopes, CLI version, and the command's error message.
A completeness check cannot judge a version	Use a version published with Skip; see the CLI's completeness gate.