# Glossa for agents

Glossa is an AI-native translation management system: push any translation file, get every language translated by Claude, dedupe strings across apps, and let agents review, audit and improve your translations over MCP, CLI and API.

## Connect

- MCP (streamable HTTP): `https://glossa-meterapp.vercel.app/api/mcp`. One tool per op.
- REST: `POST https://glossa-meterapp.vercel.app/api/v1/{op}` with the op's input as JSON. `GET https://glossa-meterapp.vercel.app/api/v1` lists every op with its JSON Schema.
- CLI: `npx @meterapp/glossa <op> --json '<json>'`, plus `push` and `pull` for files.
- Auth: `Authorization: Bearer gls_…` (workspace API key; create one in the dashboard under Settings → API keys, or with `npx @meterapp/glossa login`). MCP clients may use OAuth instead; see https://glossa-meterapp.vercel.app/.well-known/oauth-protected-resource.
- Errors are RFC 9457 problem+json with a `code`; see https://glossa-meterapp.vercel.app/docs/errors.

Claude Code:

```bash
claude mcp add --transport http glossa https://glossa-meterapp.vercel.app/api/mcp \
  --header "Authorization: Bearer gls_…"
```

## Workflows

1. Orient: `get_workspace`, `get_stats`, `list_projects`.
2. Ship strings: `push_file` (any format; new strings are deduplicated and queued for translation) → `get_job` until done → `pull_file` per locale.
3. Review queue: `claim_tasks` → decide each → `resolve_task` with one of the task's actions and a note.
4. Quality: `run_audit` for a locale with a question → `get_audit` → resolve the `audit_finding`, `rule_suggestion` and `glossary_suggestion` tasks it files.
5. Investigate: `search_units` finds a term across every source, key and translation; `get_unit` shows every key and translation of one string.

6. Billing: `get_pricing` → `get_billing` → `create_checkout_link` for a human to pay, or `subscribe` with `confirm: true` once a human approved the price and a card is saved.

## Pricing

Unit: AI translation: one source string translated into one locale by Claude. Imports and human or agent edits are free. Yearly is two months free. Full price list without a credential: `GET https://glossa-meterapp.vercel.app/api/v1/get_pricing`; human page: https://glossa-meterapp.vercel.app/pricing.

- Free (`free`): free. 2,000 AI translations a month, 3 members, 3 projects. For trying Glossa on one app.
- Pro (`pro`): $49/month or $490/year. 25,000 AI translations a month, 10 members, unlimited projects. For a product team shipping in many languages.
- Team (`team`): $199/month or $1,990/year. 150,000 AI translations a month, unlimited members, unlimited projects. For companies localizing several apps and sites.
- Enterprise (`enterprise`): custom. Volume AI translations a month, unlimited members, unlimited projects. For larger volumes, security reviews and invoicing.

Buying a plan:

- create_checkout_link {plan, interval} returns a Stripe Checkout URL; give it to a human to pay. Nothing is charged until they complete it.
- subscribe {plan, interval, confirm: true} starts or changes the plan on the card already saved for this workspace, after a human approved the price. Without a saved card it returns a checkout_url instead.
- get_billing shows the current plan, usage this month and whether a card is saved.
- CLI: `npx @meterapp/glossa pricing`, `npx @meterapp/glossa billing`, `npx @meterapp/glossa subscribe pro --interval year [--open]`.

## Task kinds

- `merge_review` (keep_merged | split): Keys that share source text were merged into one unit; split when their meaning differs.
- `merge_suggestion` (merge_into_a | merge_into_b | keep_separate): Two near-identical strings that could share one unit.
- `translation_review` (approve | edit | retranslate): A translation the model was not confident about.
- `audit_finding` (apply | edit | dismiss): A problem an audit found, with a proposed fix.
- `rule_suggestion` (add | edit | dismiss): A standing rule an audit proposes for future translations.
- `glossary_suggestion` (add | dismiss): A term an audit thinks should be fixed or never translated.
- `learn_format` (keep | retire | retry_with_hint | dismiss): A template the AI wrote for an unknown file format.

## Rules

- Never change, drop, add or reorder placeholders ({name}, {{count}}, %@, %1$s, <b>…</b>). The API rejects such translations with placeholder_mismatch.
- Never translate glossary terms marked do_not_translate (brand and product names). Call list_glossary before editing translations by hand.
- Prefer fixing the cause over the symptom: improve a unit's context with update_unit (retranslate=true), or add a rule with add_rule, instead of hand-editing many locales.
- Split a merged unit only when the keys mean different things (verb vs noun, different screens with different meaning). Identical meaning stays merged.
- Claim tasks with claim_tasks before resolving them so parallel agents do not collide; claims expire after 30 minutes.
- Resolve each task with one of the actions it lists, and leave a short note explaining the decision.
- Use read-only ops (search_units, get_unit, list_tasks) freely; writes are recorded in the activity log with your surface.
- Never buy, change or cancel a plan on your own initiative. Quote the plan and price from get_pricing, and only call subscribe or cancel_subscription with confirm: true after a human approved it; otherwise give them the create_checkout_link URL.

## Ops

### Workspace

- `get_workspace`: The workspace this credential belongs to: name, source locale and the product context every AI prompt starts with.
- `update_workspace` (write) (admin): Change the workspace name, source locale or product context.
- `get_stats`: Counts across the workspace (projects, units, keys, open tasks) and per-locale translation coverage per project.
- `list_activity`: Who changed what, from which surface (dashboard, api, mcp, cli, ai), newest first.

### Projects

- `list_projects`: Every project (app) in the workspace with its target locales.
- `create_project` (write): Add a project (one app, site or service) with the locales it ships in.
- `update_project` (write): Change a project's name, description, target locales or auto-translate.

### Files

- `list_files`: Files of a project.
- `push_file` (write): Upload a translation file in any format (JSON, YAML, xcstrings, .strings, stringsdict, strings.xml, PO, XLIFF, ARB, properties, RESX, CSV, or one Glossa learned).
- `pull_file`: Render one locale of a file in its own format, ready to write to disk.

### Formats

- `detect_format`: Which format Glossa would read a file as, with confidence and the runner-up candidates.
- `list_formats`: Built-in formats and the templates this workspace has learned, with their status.
- `learn_format` (write): Ask the AI to write a template for a file format Glossa can't read yet, from a sample.
- `approve_format` (write): Set a learned format's status (active reads files, retired stops).

### Strings

- `search_units`: Full-text and fuzzy search across every source string, key name and translation in the workspace.
- `list_units`: Page through units (deduplicated source strings) with their translation in one locale.
- `get_unit`: One unit with every key that uses it (across projects and files), all its translations and their history.
- `update_unit` (write): Set a unit's description (context for translators and the AI), max length or tags.
- `set_translation` (write): Write or correct a unit's translation in one locale.
- `review_translations` (write): Mark many translations reviewed, approved or needs_review at once, by unit and locale.
- `translate` (write): Queue AI translation.
- `merge_units` (write): Point every key of the `merge` units at the `into` unit, so they share one translation per locale.
- `split_key` (write): Give one key its own unit (a copy of the source and its translations) so it can be translated differently from the other keys that shared the string.
- `scan_duplicates` (write): Queue a scan for near-duplicate strings (same meaning, slightly different text) and file merge_suggestion tasks for them.

### Review queue

- `list_tasks`: The review queue, highest priority first.
- `claim_tasks` (write): Claim up to `limit` open tasks so parallel agents don't work the same ones.
- `resolve_task` (write): Decide a task by naming one of its actions (merge_review: keep_merged | split; merge_suggestion: merge_into_a | merge_into_b | keep_separate; learn_format: keep | retire | retry_with_hint | dismiss; translation_review: approve | edit | retranslate; audit_finding: apply | edit | dismiss; rule_suggestion: add | edit | dismiss; glossary_suggestion: add | dismiss).

### Glossary

- `list_glossary`: Glossary terms: brand and product names that are never translated, and terms with a fixed translation per locale.
- `upsert_glossary_term` (write): Add a term or change it.
- `delete_glossary_term` (write): Remove a glossary term; future translations no longer enforce it.

### Rules

- `list_rules`: Standing instructions appended to every translation prompt, globally or for one locale.
- `add_rule` (write): Add a standing instruction for future translations, e.g.
- `update_rule` (write): Edit a translation rule's text, or set active=false to stop adding it to translation prompts.

### Audits

- `run_audit` (write): Ask the AI to review one locale holistically ("How is our Spanish?
- `get_audit`: An audit's answer, score and findings (empty while its job runs; see job_status).
- `list_audits`: Past locale audits with their summary and score, newest first.

### Jobs

- `get_job`: Status and output of a background job (translate, learn_format, audit, dedupe_scan).
- `list_jobs`: Recent background jobs (translate, learn_format, audit, dedupe_scan) with status and errors, newest first.

### API keys

- `list_api_keys` (admin): API keys of this workspace (prefix only; the full key is shown once at creation).
- `create_api_key` (write) (admin): Create a workspace API key for the CLI, MCP or CI.
- `revoke_api_key` (write) (admin): Revoke an API key immediately; every CLI, CI job or MCP host using it stops working.

### Billing

- `get_pricing`: The plans (Free, Pro, Team, Enterprise) with monthly and yearly prices in cents, AI translations included a month, member and project limits, features, and how to buy.
- `get_billing`: This workspace's plan, subscription status, renewal or end date, whether a card is saved (so subscribe can charge it), and usage this month against the plan (AI translations, members, projects).
- `create_checkout_link` (write) (admin): A Stripe Checkout URL where a human pays for a plan; hand it to them (or open it in their browser).
- `subscribe` (write) (admin): Start or change this workspace's paid plan in one call, charging the card already saved for the workspace.
- `cancel_subscription` (write) (admin): Cancel the paid plan at the end of the current period (no refund; the plan stays until then, then the workspace is on Free).
- `resume_subscription` (write) (admin): Undo a cancellation that has not taken effect yet, so the plan renews as before.
- `create_billing_portal_link` (write) (admin): A private Stripe page where a human downloads invoices, updates the card or billing details, or cancels.

Full schemas: https://glossa-meterapp.vercel.app/llms-full.txt or https://glossa-meterapp.vercel.app/openapi.json.