Lingo

Lingo.dev Documentation Audit

The platform docs are well-written and the API/CLI references are unusually thorough for a v1.0 product — but the integrations section is hollowed out by dead links, two MCP servers collide on the same client name, the engine's German "deploy" example contradicts itself across two pages, and an AI-positioned platform ships neither llms.txt nor llms-full.txt.

1. All four CI/CD integration pages are 404s, linked from the docs index and sidebar (critical)

Location: /en/docs/integrations, /en/docs/integrations/github-actions, /en/docs/integrations/gitlab-ci-cd, /en/docs/integrations/bitbucket-pipelines, /en/docs/integrations/advanced-patterns

Problem: The Continuous Localization overview page promises first-party integrations and explicitly links them in its "Next Steps" panel ("GitHub Actions — Set up the official GitHub Action") and in inline prose ("For details on choosing between these, see Advanced Patterns"). All four sub-pages return a real 404:

• /integrations/github-actions → "404 — Page not found"
• /integrations/gitlab-ci-cd → 404
• /integrations/bitbucket-pipelines → 404
• /integrations/advanced-patterns → 404

The Integrations overview lists every one of these as a supported platform in a table and as a sidebar entry — so the sidebar itself contains four broken links.

Consequence: A developer following the documented setup path lands on dead pages four out of four times. There is no fallback content — no inline GitHub Action YAML, no gitlab-ci.yml example, no Bitbucket Pipe config. The repo README references uses: lingodotdev/lingo.dev@main, but inputs, secrets, branching modes, and PR vs commit behavior are all promised to live on these 404'd pages. CI/CD is one of the four headline integrations on the platform overview, and it's effectively undocumented.

The fix: Either restore the pages at the documented URLs or remove every link to them — sidebar, "Next Steps" cards, inline prose, and the platform table on /integrations. At minimum, inline a working uses: lingodotdev/lingo.dev@main example with required inputs and a LINGO_API_KEY secret on the overview page until the sub-pages exist.

2. CLI sidebar advertises i18n.json and i18n.lock reference pages that don't exist (critical)

Location: /en/docs/cli/i18n-json, /en/docs/cli/i18n.json, /en/docs/cli/i18n-lock, /en/docs/cli/i18n.lock, plus /en/docs/cli ("Next Steps" panel)

Problem: The CLI overview's "Next Steps" panel promotes a top-level reference page titled "i18n.json — Full configuration reference," and the left-hand sidebar lists both an "i18n.json" entry and a sibling "i18n.lock" entry. Every plausible slug for those two sidebar pages returns 404. A separate page does exist at /en/docs/cli/configuration titled "i18n.json Configuration" — but the sidebar lists both "Configuration" and "i18n.json" as distinct entries, so the URL the prose links to is not the URL the page lives at.

Consequence: The CLI is configured entirely through i18n.json. The one place documented as the "Full configuration reference" 404s. Developers either give up or stumble onto /cli/configuration by accident. Agents following the linked URL get a hard 404 with no machine-readable hint to retry at /cli/configuration.

The fix: Pick a canonical slug for the config reference, set up a redirect from the broken slugs, and dedupe the sidebar so it doesn't list two entries for the same content. Same for i18n.lock — either build the page or remove the sidebar entry.

3. Glossary and Brand Voice docs disagree on the German translation of "deploy" (critical)

Location: /en/docs/platform/glossaries and /en/docs/platform/brand-voices

Problem: Two pages give two different German translations for the same source word, using each other's example as the canonical illustration:

• Glossary page (Custom translations table): Deploy → Bereitstellen, en → de. Same example is repeated in the "Glossary vs. instructions vs. brand voices" comparison table: "Deploy" → "Bereitstellen".
• Brand Voice page (German example): "When a German equivalent exists for a technical term, use it (e.g., 'Bereitstellung' for deployment)".

Both pages explicitly establish the precedence rule that glossary wins over brand voice — so the example actively contradicts the precedence the docs are teaching. Bereitstellen is the verb infinitive ("to deploy"); Bereitstellung is the noun ("the deployment"). Different parts of speech, different rendered output.

Consequence: Anyone copying the examples into a real engine gets inconsistent output and may not realize why. Worse, the contradiction lives inside the canonical worked example used to teach the layer-precedence model — the one concept the engine is built around. Agents reading both pages cannot reconcile which value to use when configuring a new engine programmatically.

The fix: Pick one rendering, align both pages, and add a one-line note explaining the part-of-speech choice (since "deploy" is both a verb and a noun in English, the German equivalent depends on context).

4. Pipeline doc tells readers to "See Reports for aggregate stage success rates" — no such report exists (significant)

Location: /en/docs/api/pipeline and /en/docs/platform/reports

Problem: The Async Localization Pipeline page closes its "Stages at a glance" section with: "Each step is marked completed, failed, or skipped independently. … See Reports for aggregate stage success rates." The Reports page lists exactly eight reports — Word Generations, Token Consumption, Top Locales, Glossary Depth, Change Rate, Average Scores, Terminology Coverage, Instruction Adherence — and none of them measure pipeline stage success.

Consequence: Operators relying on the pipeline (pre-edit, human review, post-edit, back-translation drift check) cannot answer the operational question the docs explicitly tell them to answer: "are my pipeline stages succeeding?" The cross-reference is a dead end, but reads as a real promise.

The fix: Either ship the report and add it to the Reports page table, or drop the cross-reference and replace it with what's actually observable today (e.g., per-job warnings arrays from the job status response).

5. No llms.txt or llms-full.txt on a platform whose primary pitch is to AI agents (significant)

Location: https://lingo.dev/llms.txt, https://lingo.dev/llms-full.txt

Problem: Both URLs return HTTP 404. The platform docs explicitly position MCP integration with Claude Code, Cursor, GitHub Copilot, ChatGPT, Codex, and Claude Desktop as a headline feature; the React MCP page boasts that an agent can complete i18n setup "in minutes." The same site does not publish the standard agent-discovery file that lets those agents index its own docs.

Consequence: AI coding assistants pulling Lingo docs at indexing time get nothing structured — no curated entry points, no list of canonical reference pages. This matters more for Lingo than for an average vendor, because the docs explicitly advertise the product to that audience. The mismatch is also a credibility issue: the product tells you to point your agent at Lingo, while Lingo's own site doesn't point agents anywhere.

The fix: Publish llms.txt (curated list of canonical docs) and llms-full.txt (flattened full-text bundle). Include the API reference, the CLI reference, both MCP setup pages with their distinct URLs, and the changelog.

6. Two MCP servers, same client name "lingo" — installing both clobbers the first (significant)

Location: /en/docs/platform/mcp and /en/docs/react/mcp/setup

Problem: Lingo ships two distinct MCP servers at two distinct URLs:

• Platform MCP — https://mcp.lingo.dev/account — manages engines, glossary, brand voice, instructions.
• React i18n MCP — https://mcp.lingo.dev/main — walks an agent through setting up i18n in a Next.js / Vite / React Router project.

Both setup pages document the install with the same client name:

claude mcp add lingo --transport http https://mcp.lingo.dev/account --scope user
claude mcp add --transport http "lingo" https://mcp.lingo.dev/main

And the JSON config snippet on the platform MCP page uses "lingo" as the top-level key. Running both commands collides — the second overwrites the first in ~/.claude/settings.json. Neither page warns about this, and neither page acknowledges that the other server exists.

Consequence: A developer who follows both setup guides (an entirely reasonable thing to do — they're separate features) ends up with whichever they installed last. Then engine-management calls or i18n-checklist calls fail silently in the agent. Debugging this requires reading both pages and realizing the keys are identical.

The fix: Use distinct client names: lingo-engine for /account and lingo-i18n for /main. Add a one-line note on each setup page acknowledging the other server and the name choice. Update Claude Code/Cursor/etc. snippets accordingly.

7. Auth setup contradicts itself between CLI Setup and Connect Your Engine; [auth.vnext] undefined (significant)

Location: /en/docs/cli/setup (Step 3) and /en/docs/platform/connect-your-engine (Step 2)

Problem: Two CLI pages document API-key persistence differently and don't cross-reference each other:

• CLI Setup: export LINGO_API_KEY="your-api-key" — env var only.
• Connect Your Engine: "Or persist it in ~/.lingodotdevrc:" followed by an INI block with a header [auth.vnext]. Nothing on the page explains what vnext means, why it's vnext rather than auth, whether [auth] is the stable/old name, or whether the name will change.

Consequence: A developer following the "Getting started" path on Setup never learns about the rc file, and a developer on Connect Your Engine has to trust a header section whose name implies it's a versioned/experimental contract — without any explanation. Agents writing config files have no way to know whether [auth.vnext] is the current canonical key or about to be renamed.

The fix: Cross-link the two pages. Document ~/.lingodotdevrc in CLI Setup as the persistent option alongside the env var. Either rename [auth.vnext] to [auth] (and add an alias for backward compatibility), or document explicitly what "vnext" means and when it stabilizes.

8. 402 Payment Required and 429 Too Many Requests are the only place "credits" and "daily token quota" appear in the docs (significant)

Location: /en/docs/api

Problem: The error-codes table on the API overview is the only place in the entire docs site that mentions "credit limit" or "daily token quota":

• 402 Payment Required — "Organization has hit its credit limit"
• 429 Too Many Requests — "Organization has hit its daily token quota — upgrade the plan to raise the limit"

There is no linked pricing page, no credits page, no quota reference, no docs on how credits are consumed, how to check remaining credits, how the daily quota resets, or what "upgrade the plan" means. The Reports page tracks token consumption but never ties it to credits or quotas.

Consequence: A developer hitting either error has no programmatic or documented path to diagnose it. They know they hit "the credit limit" but cannot find out what one credit is, how many they had, or how to buy more. Agents handling the error cannot offer the user a remediation other than "try again later."

The fix: Add a Billing / Credits / Quotas section to the docs covering: what a credit is, how the daily quota is calculated and when it resets, how to inspect current usage via the dashboard or API, and how to upgrade. Link it from the 402 and 429 rows.

9. Engine/glossary/brand-voice/instruction CRUD is reachable via MCP but has no documented REST API (significant)

Location: /en/docs/api/* and /en/docs/platform/mcp

Problem: The MCP server page lists the operations an agent can perform: "create glossary entries, adjust brand voice, add instructions, configure models, and manage API keys." The REST API pages (/api, /api/localize, /api/recognize, /api/localization, /api/pipeline, /api/provisioning) document only six things: POST /process/localize, POST /process/recognize, POST /jobs/localization, the WebSocket/webhook listeners, and POST /jobs/provisioning. There is no documented endpoint for GET/POST/PATCH/DELETE on engines, glossary items, brand voices, instructions, or AI reviewers.

Consequence: Two equivalent surfaces (REST and MCP) provide drastically different capability sets. Teams that want to manage glossaries from their own backend or CI (rather than via an LLM tool call) have no documented path. The Async Provisioning API can create a fully configured engine once, but cannot modify it afterward via documented endpoints. This forces all post-provisioning automation through either the dashboard UI or the MCP tool layer.

The fix: Either publish OpenAPI documentation for the engine/glossary/brand-voice/instruction endpoints that the MCP server clearly calls under the hood, or document explicitly that those operations are MCP-only and dashboard-only and explain why.

10. Team page documents only one role ("Admin"); RBAC is gated behind "reach out to the Lingo.dev team" (significant)

Location: /en/docs/platform/team

Problem: The Team page lists exactly one role: "Admin — Full access — manage engines, API keys, team members, billing, and all settings." Every invited member becomes an admin by default. The page's only acknowledgement of granular role-based access control is a single line: "If your organization needs granular role-based access control, reach out to the Lingo.dev team."

Consequence: Lingo handles API keys, model billing, and translation requests — the kind of platform where any serious customer's security review will fail an "all-admin" model. Anyone removed from the team also has their personally-created API keys left active by default (per the same page) — so the access-management story compounds. There is no documented way to scope a CI service account, a read-only auditor, or a billing-only role without contacting sales.

The fix: Either publish the actual roles that are available behind the "reach out" gate (with permission matrices), or commit to a target date and link to it. If RBAC truly only exists as a custom contract, say so explicitly so security reviewers can plan around it.

11. /process/recognize has no documented auth section, error codes, or quota behavior (minor)

Location: /en/docs/api/recognize

Problem: The Localize endpoint page documents an explicit X-API-Key header, the full error-codes table (400/401/402/403/404/429/500), and the new usage/model response object. The Recognize page documents none of these. It shows only a request shape, a response shape, and a note about regional markers — with no authentication block, no error-code table, no statement of whether recognize consumes credits or counts against the daily token quota, and no rate-limit guidance. The /en/docs/api overview's error table reads as if it covers the whole API, but the Recognize page never says "errors are documented in the API overview."

Consequence: A developer wiring up language detection has to guess whether 401/402/429 behavior matches /localize, whether recognize requests are metered, and what happens on malformed input. Agents calling recognize and getting non-2xx responses have no documented error vocabulary.

The fix: Add an Authentication and Error codes section to the Recognize page (or an explicit cross-reference to /api's error table) and state whether recognize requests count toward credits and the daily token quota.

12. Model catalog uses inconsistent name formats and a small named shortlist (minor)

Location: /en/docs/platform/llm-models

Problem: The "notable models" table spells out only seven model names across six providers while the page headline claims "400+ models." More concretely, the page's model-config example mixes name formats in a single field: gpt-4o (provider-slug only) alongside claude-sonnet-4-5-20250514 (provider-slug with date stamp). A separate fallback example uses informal display names ("Claude Sonnet," "Gemini Flash") that don't match either of those two formats. The page says "The full model catalog … is available on the LLM Models page" — circularly, since this is that page.

Consequence: An agent (or human) writing a config file based on the example has no clean rule for which name format the API actually accepts. A user looking for a model not in the seven-name shortlist has no link to the full catalog the prose promises.

The fix: Pick one canonical model-name format and use it everywhere on the page; replace informal display names in examples. Either link to a live, generated catalog (sortable by provider/context window) or remove the "available on the LLM Models page" sentence, since this is that page.

13. Format-count claims disagree across CLI overview, Supported Formats, and the GitHub README (minor)

Location: /en/docs/cli, /en/docs/cli/supported-formats, github.com/lingodotdev/lingo.dev README

Problem: Three different surfaces give three different answers to "what file formats does the CLI support?"

• CLI overview "Next Steps" panel: "JSON, YAML, Markdown, and 20+ file formats"
• Supported Formats page: 29 distinct bucket types in the table
• GitHub README: "JSON, YAML, markdown, CSV, and PO files" — five formats

Consequence: A developer evaluating Lingo via GitHub thinks it handles five formats; the docs landing page advertises 20+; the actual reference says 29. Anyone making a procurement-style comparison against alternatives will pick whichever number matches their first source. Agents reading the README first will conclude the tool can't handle XLIFF, Android XML, Xcode strings, etc., when in fact it can.

The fix: Pick the real number and propagate it. The README is the most-visible artifact and the most outdated — update it first.

14. AI Reviewers page reads as truncated mid-word — verify before publishing (minor)

Location: /en/docs/platform/ai-reviewers

Problem: In the scraped snapshot, the "AI reviewer reports" section ends mid-sentence: "Pass rates over time - for boolean AI reviewers, plotted as dail". This may be a scraper artifact rather than the live page state, but the same section is the only place in the docs that links AI Reviewers to the Average Scores / Terminology Coverage / Instruction Adherence reports — so even a partial cut on this page breaks the conceptual bridge between the AI Reviewers feature and the quality reports.

Consequence: If the page is truly truncated in production, readers and agents miss the description of how reviewer reports are visualized. If it's a scraper artifact, the section is still long enough to be at risk of getting cut by any indexer.

The fix: Verify the page renders to completion in production. Either way, make the linkage between AI Reviewers and the three quality reports explicit and complete on this page.

What they do well

• The API reference for /process/localize is genuinely strong: every field documented, request/response shapes shown, the new usage/model/cost object explained, and the "when fields are absent" callout precisely tells you the short-circuit condition.
• The engine layer-precedence model (glossary > instructions > brand voice) is taught clearly and consistently across the Engines, Glossaries, Instructions, and Brand Voices pages — the contradiction in finding #3 is a content error inside an otherwise well-modeled concept.
• The Async Localization API + Pipeline pages do a rare thing well: they describe both the happy path and the failure semantics (timeouts, skipped stages, completed_with_warnings, per-step warnings arrays) instead of pretending the system always succeeds.

Top 3 recommendations

1. Fix the dead-link sprawl in /integrations/* and /cli/i18n* — either build the pages or remove every link to them, including from the sidebar.
2. Publish llms.txt and llms-full.txt. On a platform that pitches itself to AI coding agents, their absence is the single biggest credibility hole.
3. Reconcile the Glossary / Brand Voice German "deploy" example — the contradiction sits inside the canonical worked example used to teach the engine's core precedence rule.