Using Lantern

Lantern is a localization manager: an organization holds projects, a project holds translation keys, and each key has a value in every language. You edit values in a grid, collaborate, and your apps pull (and optionally push) the result through the API.

Live instance: https://lantern.abyss-inn.ch

1. Account, organizations & projects#

1. Sign up with name, email, and a password (≥ 8 chars), then sign in. We email you a verification link — until you confirm your address, a banner reminds you and you can't create or join organizations. Use Resend in the banner if it doesn't arrive.
2. Create an organization (or get added to one). The creator is its owner. Collaboration lives at the org level — members can access every project in the org.
3. Inside an org, create a project (name + optional description). The org has tabs Projects, Members, Roles and Settings (Roles/Settings show only if you can manage them).
4. Switch orgs/projects from the top bar; click 🏮 Lantern to go back.

Each project has the tabs Editor, Glossary, Import / Export, API, Members and Activity — plus Settings, which only an owner sees.

Deleting a project lives on that Settings tab. It is permanent and takes everything with it: every key, translation, comment, glossary term and API token in the project. You have to type the project's name to confirm, and the deletion is recorded in the organization's activity.

Two-factor authentication (optional). From Account, enable two-factor authentication: scan the QR code with an authenticator app (or paste the key manually), confirm a 6-digit code, and save the 10 one-time backup codes shown once. After that, signing in asks for a code from your app — or one of your backup codes if you lose your device. You can regenerate backup codes or disable 2FA from Account (both require a current code). Your TOTP secret and backup codes are never included in a data export.

2. Roles & permissions#

Access is permission-based. Every org has three built-in roles; the owner always has every permission and can't be locked out.

Custom roles. On the org Roles tab, an owner/admin can define a custom role as any set of these permissions (e.g. a "Reviewer" who can edit and mark reviewed but not create keys), then assign it to a member on the Members tab. Custom roles apply across every project in the org, just like the built-in ones.

3. Languages#

On the Editor tab, owners/admins add a language by locale code (e.g. en, fr, de-CH) and a display name. The first language becomes the default. Locale codes are what the API returns and what your files are named after, so pick the codes your app expects. Remove a language with the ✕ on its chip (this deletes its values).

4. Keys#

Add a key with an optional namespace, a name, and an optional description. The key's full path is namespace.name (or just name with no namespace) — e.g. namespace home + name title → home.title.

A key is rejected if its full path already exists, even via a different split (home+title collides with a plain home.title). Pick one convention.

Use the search box to filter keys. Owners/admins can edit a key (rename, change its namespace or description) with the ✎ next to it — the edit keeps all existing translations, statuses and comments attached — or delete it with the ✕.

5. The editor grid#

Rows are keys, columns are languages. Type a value into a cell — it saves automatically when you leave the field (only if changed).

• Status dot next to each cell: gray = untranslated (empty), green = translated, blue = reviewed. Click a green dot to mark it reviewed; click again to unmark. Editing a reviewed value resets it to translated.
• Completion bars at the top show each language's progress (filled values / total keys), updating live as you type.
• Needs review checkbox filters to keys that have translated-but-not-yet-reviewed values — handy for a reviewer pass.
• Assignees — assign one or more members to a key to make ownership clear (who's translating / reviewing it). Click the avatar stack (or the ➕ on an unassigned key) to pick members from a checklist; their avatars show on the key in the grid and detail views. Only members with access to the project are assignable, and each assignee gets an in-app notification. Assigning needs the assign keys permission (owners/admins/members by default). Changes show up in the activity feed under Assignments.

6. Comments#

Each key row has a 💬 button with a count. Open it to read the thread and add a comment — useful for context ("keep under 20 chars", "this is a button label", etc.).

7. Glossary#

The Glossary tab holds a project's approved terms — product names, brand words, and tricky vocabulary you want translated consistently. For each term you can add a description, an approved translation per language, mark it do-not-translate (a brand name to keep verbatim), or case-sensitive. Anyone can read the glossary; managing it needs the manage glossary permission (owners/admins by default).

In the editor's Focus view, words in the source text that match a glossary term are highlighted — hover to see the approved translation for the language you're translating into, or a "do not translate" note. Term changes show up in the activity feed.

8. Members & roles#

Members are managed at the organization level (the org's Members tab), not per project — a member can reach every project in the org. The owner (or anyone with the manage members permission) can invite someone by email with a chosen role (Admin, Member, or any custom role). The invitee gets an email link and joins once they accept — you can invite an address that doesn't have a Lantern account yet (they sign up, confirm their email, then accept). Pending invitations are listed on the Members tab, where you can resend or revoke them; once someone has joined you can change their role or remove them. Build custom roles on the org's Roles tab (see §2).

9. Import / Export#

On the Import / Export tab:

• Import
  • JSON — handles flat {"home.title": "..."} and nested {"home": {"title": "..."}}. Import several locales at once: select multiple files (the locale is read from each filename — en.json, de-CH.json — and shown for you to override), or upload a single object keyed by locale ({"en": {…}, "fr": {…}}) and tick keyed by locale.
  • CSV / XLSX — a key column plus one column per locale; merges across languages.
  • All formats merge (existing values updated, new keys added), auto-create missing languages (needs the add / remove languages permission), skip blank cells (won't wipe values), and log a single entry in the activity feed.
• Export
  • JSON for one language (flat or nested), or CSV / XLSX covering all.

Import is the bulk way to get keys in; the API (INTEGRATION.md) is the automated way to get translations out into your apps.

10. API tokens#

On the API tab, owners/admins create a token, scoped to that project. The token string is shown once — copy it then. List shows each token's name, prefix, and last-used time; revoke any token to cut off access immediately.

Tokens are read-only by default. Expand Write permissions when creating one to grant scopes (e.g. create keys, edit translations) so an AI agent or CI script can push keys and values back — see the write section in INTEGRATION.md.