Skip to main content

How to migrate from Lokalise to i18n-keyless

· 8 min read
Arnaud Ambroselli
Founder of i18n-keyless

If you're on Lokalise but you've realized you're not actually using TMS features — no translators, no glossaries, no in-context review — and Lokalise has just become an expensive JSON-file storage with AI auto-translate enabled, this guide walks through migrating to i18n-keyless.

If you do use Lokalise's TMS features (translator team, glossaries, branding workflows), don't migrate. Read the comparison — Lokalise is the right tool for that workflow.

TL;DR​

  1. Export translations from Lokalise as flat JSON, one file per locale.
  2. Install i18n-keyless alongside whatever client library you currently use (likely i18next or react-intl driven by Lokalise's CLI).
  3. Import translations into the i18n-keyless backend so users see no regression.
  4. Sweep code file-by-file, replacing t("key") calls with <I18nKeyless>.
  5. Remove Lokalise CLI, the GitHub integration, the locale files in your repo, and the TMS subscription.

The migration usually takes 1–3 sprints, depending on app size and which client library Lokalise is feeding.

Who this guide is for​

This guide assumes you're using Lokalise mostly as a translation pipeline:

  • Translations get pushed/pulled via lokalise-cli or the GitHub integration.
  • Your code references translations via i18next (or react-intl, or another client library) — Lokalise just feeds the locale files.
  • You don't have a translator team actively logging into Lokalise's UI.

If your team does actively use Lokalise's translator UI, glossaries, and review workflows, stay on Lokalise. We don't replace those.

Step 1: Export translations from Lokalise​

Use the Lokalise CLI or web UI to export translations as flat JSON, one file per locale:

# CLI export
lokalise2 file download \
  --token YOUR_LOKALISE_TOKEN \
  --project-id YOUR_PROJECT_ID \
  --format json \
  --bundle-structure "%LANG_ISO%.json"

You'll end up with en.json, fr.json, de.json, etc. Same shape as the i18next migration.

Step 2: Install i18n-keyless​

npm install i18n-keyless-react

Initialize alongside your existing client (don't remove anything yet):

import * as I18nKeyless from "i18n-keyless-react";

I18nKeyless.init({
  API_KEY: "YOUR_API_KEY",
  storage: window.localStorage,
  languages: {
    primary: "en",
    supported: ["en", "fr", "de", "es"],
  },
});

See the quick-setup guide for storage options.

Step 3: Import existing translations to i18n-keyless​

Same approach as the i18next migration — for each English string, you have the corresponding French / German / etc. translation. Import all of them so users see no regression on switch.

import en from "./locales-from-lokalise/en.json";
import fr from "./locales-from-lokalise/fr.json";
import de from "./locales-from-lokalise/de.json";

function flatten(obj: any, prefix = ""): Record<string, string> {
  const out: Record<string, string> = {};
  for (const k of Object.keys(obj)) {
    const v = obj[k];
    const key = prefix ? `${prefix}.${k}` : k;
    if (typeof v === "string") out[key] = v;
    else Object.assign(out, flatten(v, key));
  }
  return out;
}

const enFlat = flatten(en);
const frFlat = flatten(fr);
const deFlat = flatten(de);

const records = Object.entries(enFlat).map(([key, sourceText]) => ({
  source: sourceText,
  translations: {
    fr: frFlat[key] ?? null,
    de: deFlat[key] ?? null,
  },
}));

// POST to the i18n-keyless API to pre-populate translations.

Step 4: Migrate the code​

The code-level migration depends on which client library Lokalise is feeding:

  • Lokalise + i18next (most common) → follow the i18next migration guide. Replace t("key") calls with <I18nKeyless>.
  • Lokalise + react-intl → follow the react-intl migration guide.
  • Custom client → the pattern is the same: dual-run, sweep file-by-file, replace key references with <I18nKeyless> source strings.

Step 5: Remove the Lokalise pipeline​

Once your code no longer references the locale files Lokalise was feeding:

  1. Disable the Lokalise GitHub integration (Settings → Integrations in Lokalise UI). This stops auto-PRs.
  2. Delete .lokalise.config / lokalise.yml from your repo.
  3. Delete the locale JSON files in public/locales/ (or wherever they live).
  4. Uninstall @lokalise/node-api / lokalise2 CLI if installed locally: 
    npm uninstall @lokalise/node-api
  5. Cancel your Lokalise subscription (or downgrade if you keep it for unrelated projects).

Keep your Lokalise project archived (don't delete it) for a quarter, just in case you want to roll back.

What you lose​

Be honest about what you're giving up:

  • Lokalise's translator UI. If you ever want to bring on translators, you lose this. You'd have to add them to i18n-keyless's dashboard (which is override-only, not a full translator workflow) or pick a TMS again.
  • Translation memory across projects. If you have multiple Lokalise projects sharing TM, that disappears. Each i18n-keyless project is independent.
  • Glossaries and brand consistency tooling. Same — gone.
  • In-context preview / screenshot annotations. Not a feature in keyless.
  • Lokalise's machine translation marketplace (DeepL, Google, etc.). i18n-keyless uses Mistral; you don't choose the provider.

What you gain:

  • No Lokalise CLI, no GitHub auto-PRs, no locale files in the repo.
  • AI translations for new strings without manual project setup.
  • Faster setup for adding new locales.
  • Lower cost (typically) for engineering-led teams with no translation workflow.

Common gotchas​

Lokalise auto-PRs after migration​

If you don't fully disable the GitHub integration, Lokalise will keep generating PRs to your repo even after you've stopped reading from those locale files. They become silent noise. Disable the integration explicitly in Lokalise's settings.

Locale files in .gitignore​

Some teams .gitignore their locale files (treating them as build artifacts pulled from Lokalise at deploy time). After migration, there are no locale files at all — but check your build pipeline doesn't break expecting them to exist.

Branch-based Lokalise projects​

Some teams have one Lokalise project per branch (feature branches, release branches). The migration swaps "branch-aware locale files" for "single source of truth in keyless". This usually simplifies the workflow but adjust your CI accordingly.

Custom keyboard / locale keyboards in Lokalise​

If you used Lokalise to manage locale-specific assets that aren't strings (e.g., legal documents per country, marketing assets), keyless doesn't manage those — they need a different solution.

When NOT to migrate from Lokalise​

We say this in the comparison too, but worth restating: if you genuinely use TMS features, stay on Lokalise. Specifically:

❌ You have translators logging into Lokalise's UI weekly. ❌ Brand glossaries enforce specific terminology. ❌ You have a structured review workflow with assigned reviewers. ❌ You localize content beyond UI strings (marketing pages, legal text, support articles) where human translators add real value. ❌ You have 30+ locales with strict consistency requirements.

If 3+ of these apply, the right move isn't to migrate — it's to lean further into Lokalise's TMS features.

FAQ​

Can I migrate without exporting all translations first?​

You could — and let i18n-keyless's AI re-translate everything from scratch. But you'd lose any human-edited translations Lokalise had on file. Always export first.

How long is the dual-run window?​

As long as you need. Most teams complete the sweep in 2–3 sprints. The dual-run is reversible until you delete the Lokalise integration and locale files.

Will my Lokalise data be lost if I cancel?​

Lokalise typically retains project data for a period after cancellation (check their current policy). To be safe, export everything to JSON before cancelling and keep a backup.

What if my client library is Lokalise's SDK directly?​

If you use @lokalise/i18n or similar Lokalise-specific SDKs (less common), the code-level swap is more involved — you'd be replacing both the TMS and the runtime library at once. The dual-run approach still works; expect more code touch points.

Do I lose the cost savings if I keep Lokalise for one project?​

You can keep Lokalise on a smaller plan for the projects that genuinely need it, while moving the rest to keyless. They're not mutually exclusive at the company level — only at the per-project level.

Next steps​