DialectOS

🌎 DialectOS

TL;DR: DialectOS — open-source MCP server and CLI for translating and QA-checking content across 25 regional Spanish variants. Best for AI agents, documentation teams, and app developers localizing into Spanish.

A Model Context Protocol server built specifically for Spanish dialects.

DialectOS is an open-source Spanish dialect translation server that runs as an MCP (Model Context Protocol) tool and CLI. It translates English and other languages into 25 regional Spanish variants — Mexican, Argentinian, Colombian, Puerto Rican, and more — while preserving markdown structure, enforcing glossary terms, and applying adversarial quality gates that catch semantic drift before it reaches users.

Translate, detect, and adapt content across 25 regional Spanish variants while preserving markdown structure, code comments, and locale file formatting.

📖 Documentation · 🚀 Quick Start · 🛠️ MCP Tools · Agent Skill · 📦 Packages · 🤝 Contributing · 📋 Roadmap

---

Public Discovery

DialectOS is a Spanish localization and dialect QA system for AI agents, documentation teams, app developers, and support organizations. It provides MCP tools, CLI workflows, glossary enforcement, locale-file validation, and adversarial quality gates for regional Spanish variants.

AI discovery: llms.txt provides a compact project summary for AI assistants and search crawlers.

Best-fit searches: Spanish dialect translation MCP server, Spanish localization QA, Model Context Protocol translation tool, i18n validation CLI, regional Spanish translator, glossary enforcement, AI localization audit, Spanish launch certification.

Agent Skill

DialectOS includes a public agent skill at skills/dialectos/SKILL.md. Use $dialectos in compatible agent hosts when you want an agent to choose the right MCP or CLI workflow for regional Spanish translation, markdown preservation, locale-file validation, glossary enforcement, register checks, and launch-readiness QA.

Spanish Launch Certification

DialectOS is available as a paid Spanish localization launch audit. We certify your Spanish docs, app strings, support macros, or locale files across target dialects and deliver an MQM-aligned launch-readiness report.

• Beta pilot: $500
• Scope: up to 10,000 source words and 5 target dialects
• Deliverables: certification report, issue list, severity table, recommended fixes, launch decision
• Sample report: audits/sample-customer-report.md
• Offer details: docs/spanish-launch-certification.md

✨ What makes DialectOS different?

Coverage is not equal across the 25 variants. es-AD, es-BZ, es-PH, es-GQ and es-US are experimental: their profiles lean on contact-language markers (Catalan, Kriol, Tagalog, English) and have thinner vocabulary and test data than the major variants.

Dialect detection is a keyword heuristic. Its last recorded top-1 accuracy was 54.8% on the bundled detection corpus, and that corpus was written from the detector's own keyword lists, so the figure is not an independent measure. Treat detect_dialect output as a hint, not a verdict.

---

🎯 Why this exists

*"We shipped a product to Mexico using our Spain Spanish translations. Users thought we were being intentionally rude."*

Spanish is not one language — it's 25 regional variants with different vocabulary, formality levels, slang, and grammatical preferences. Existing translation tools treat Spanish as a monolith.

DialectOS solves this by:

• Understanding regional differences (es-MX vs es-ES vs es-AR vs es-CO...)
• Preserving technical document structure during translation
• Providing glossary enforcement for consistent terminology
• Adding semantic context, dialect grammar profiles, quality contracts, and quality gates that catch drift before it reaches users
• Running as an MCP server so AI assistants can translate natively

---

🚀 Quick Start

Install note: DialectOS v0.3.2 is distributed as GitHub Release tarballs. GET https://registry.npmjs.org/@kyanitelabs/dialectos and GET https://registry.npmjs.org/dialectos both return 404 — there is no npm package. The CLI and MCP tarballs bundle the unpublished @dialectos/* workspace packages, so a single pnpm add -g / pnpm dlx of the tarball URL works. Clone the repo only for local development or the browser demo.

MCP setup

Add the released MCP server to Claude Desktop, Cursor, or any MCP client:

{

"mcpServers": { "dialectos": { "command": "pnpm", "args": [ "dlx", "https://github.com/KyaniteLabs/DialectOS/releases/download/v0.3.2/dialectos-mcp-0.3.2.tgz" ], "env": { "LLM_API_URL": "https://your-llm-gateway/v1/chat/completions", "LLM_MODEL": "your-dialect-capable-model", "LLM_API_KEY": "your-key-if-required", "LLM_API_FORMAT": "openai", "ALLOWED_LOCALE_DIRS": "/path/to/locales" } } } }

ALLOWED_LOCALE_DIRS is a comma-separated list of the only directories the server may read or write; when set, it replaces the working directory. Without it the server falls back to its working directory, but never to / or your home directory, so set it when your client starts servers from either.

For local development from a source checkout, run pnpm build and point your MCP client at packages/mcp/dist/index.js.

Full-app browser demo

The browser demo requires a source checkout.

The browser demo is no longer a fake/static rule replacer. It calls a local DialectOS backend, and that backend calls the configured provider stack.

LLM_API_URL="http://127.0.0.1:1234/v1/chat/completions" \

LLM_API_FORMAT="openai" \ LLM_MODEL="your-local-model-name" \ LLM_ALLOW_LOCAL=1 \ pnpm demo

Open http://127.0.0.1:8080.

For the beginner container walkthrough, see docs/full-app-demo.md.

Recommended certified models

For v0.3.0, the recommended default cloud model is glm-4.5-air through the Z.ai international Anthropic-compatible endpoint. It passed basic, expanded adversarial, and long-document certification. Use glm-5.1 when you want the higher-confidence/premium option, and qwen3.5-9b via LM Studio for local/offline certification.

export LLM_API_URL="https://api.z.ai/api/anthropic/v1/messages"

export LLM_MODEL="glm-4.5-air" export LLM_API_FORMAT="anthropic" export LLM_API_KEY="..."

LM Studio local model testing

Start LM Studio's local server, then point DialectOS at any downloaded local model. LLM_API_FORMAT=lmstudio uses LM Studio's native REST API and loads the model just-in-time when needed.

LM_STUDIO_URL="http://127.0.0.1:1234" \

LLM_MODEL="publisher/model-key-or-api-identifier" \ LLM_API_FORMAT="lmstudio" \ pnpm dialect:eval -- --live --provider=llm --out=/tmp/dialectos-lmstudio-eval

Incremental provider certification

Use dialect:certify for long local-model or cloud-provider runs. It writes events.jsonl, progress.json, and an incrementally updated results.json after every sample, with per-sample timeout protection.

LM_STUDIO_URL="http://127.0.0.1:1234" \

LLM_MODEL="qwen3.5-9b" \ LLM_API_FORMAT="lmstudio" \ pnpm dialect:certify -- --live --provider=llm --sample-timeout-ms=300000 --out=/tmp/dialectos-certify

Adversarial dialect certification

Use dialect:certify:adversarial to run paraphrase, dialect-collision, taboo-copy, placeholder, register, and repeatability traps. It wraps dialect:certify and writes a failure-matrix.md plus aggregate repeatability results.

pnpm dialect:certify:adversarial -- --live --provider=llm --repeat=2 --sample-timeout-ms=300000 --out=/tmp/dialectos-adversarial

Long-document certification

Use dialect:certify:documents to certify README/API-doc/locale JSON flows, not just sentence fixtures. It checks markdown structure, placeholders, URLs, code fences, API tables, and locale JSON outputs.

pnpm dialect:certify:documents -- --live --provider=llm --dialects=es-MX,es-PA,es-PR --out=/tmp/dialectos-doc-cert

Customer-facing certification report

Use dialect:report to turn certification artifacts into a customer-facing Markdown deliverable for paid launch audits.

pnpm dialect:report -- --input=audits/release-candidate-2026-04-22/model-matrix.json --out=customer-report.md --customer="Acme SaaS" --product="Spanish launch"

CLI install

# Install the v0.3.2 CLI tarball from the GitHub Release

pnpm add -g https://github.com/KyaniteLabs/DialectOS/releases/download/v0.3.2/dialectos-cli-0.3.2.tgz

Or use a local source checkout

pnpm install --frozen-lockfile pnpm build

Translate to Mexican Spanish

dialectos translate "Hello world" --dialect es-MX

Translate a README preserving structure

dialectos translate-readme README.md --dialect es-AR --output README.ar.md

Validate an existing translation

dialectos validate --source "Click the button" --translated "Haz clic en el botón" --dialect es-MX

Validate translation files

dialectos validate --source-file en.json --translated-file es-MX.json --dialect es-MX --format json

View translation corpus statistics

dialectos corpus stats

Run dialect quality benchmark

dialectos benchmark run --dialects es-MX,es-AR,es-ES

Generate glossary suggestions from corrections

dialectos glossary suggest --min-occurrences 3

Compare two glossary versions

dialectos glossary diff glossary-v1.json glossary-v2.json

Detect missing i18n keys

dialectos i18n detect-