DialectOS

<p align="center">
  <img src="assets/dialectos-hero.webp" alt="DialectOS — Spanish dialect localization MCP server: translate and QA across 25 regional variants" width="100%">
</p>

<div align="center">

# 🌎 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.

**The first 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.

[![CI](https://github.com/KyaniteLabs/DialectOS/actions/workflows/ci.yml/badge.svg)](https://github.com/KyaniteLabs/DialectOS/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/KyaniteLabs/DialectOS/actions)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](package.json)
[![pnpm](https://img.shields.io/badge/pnpm-11.12.0-orange)](package.json)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
[![Security](https://img.shields.io/badge/security-hardened-success)](https://github.com/KyaniteLabs/DialectOS/security)

[📖 Documentation](https://github.com/KyaniteLabs/DialectOS#readme) ·
[🚀 Quick Start](#quick-start) ·
[🛠️ MCP Tools](#mcp-tools) ·
[Agent Skill](#agent-skill) ·
[📦 Packages](#packages) ·
[🤝 Contributing](CONTRIBUTING.md) ·
[📋 Roadmap](ROADMAP.md)

</div>

---



## 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`](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`](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`](audits/sample-customer-report.md)
- Offer details: [`docs/spanish-launch-certification.md`](docs/spanish-launch-certification.md)

## ✨ What makes DialectOS different?

| Feature | Google Translate | DeepL API | **DialectOS** |
|---------|-----------------|-----------|---------------|
| Spanish dialect awareness | ❌ Generic "Spanish" | ⚠️ Limited variants | ✅ **25 regional variants** |
| MCP native integration | ❌ | ❌ | ✅ **17 MCP tools** |
| Markdown structure preservation | ❌ | ❌ | ✅ **Tables, code blocks, links intact** |
| i18n locale file support | ❌ | ❌ | ✅ **JSON locale diff & merge** |
| Gender-neutral language | ❌ | ❌ | ✅ **elles / latine / -x** |
| Formality checking (tú vs usted) | ❌ | ❌ | ✅ **Cross-dialect consistency** |
| Adversarial quality gates | ❌ | ❌ | ✅ **Semantic drift + structure validation** |
| LLM-first dialect adaptation | ❌ Generic MT | ⚠️ Limited dialect control | ✅ **Any OpenAI/Anthropic/LM Studio local LLM + dialect contracts** |
| Translation validation (any provider) | ❌ | ❌ | ✅ **`dialectos validate` — standalone correctness check** |
| GitHub CI integration | ❌ | ❌ | ✅ **Composite action for PR validation** |
| Auto-glossary from corrections | ❌ | ❌ | ✅ **Learns from user feedback** |
| Public benchmark suite | ❌ | ❌ | ✅ **205 adversarial samples across 25 dialects** |

---

## 🎯 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.0 is distributed through GitHub Release tarballs, not the npm registry. Use the released MCP/CLI tarballs for agent and command-line installs; 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:

```json
{
  "mcpServers": {
    "dialectos": {
      "command": "pnpm",
      "args": [
        "dlx",
        "https://github.com/KyaniteLabs/DialectOS/releases/download/v0.3.0/dialectos-mcp-0.3.0.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"
      }
    }
  }
}
```

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.

```bash
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`](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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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

```bash
# Install the v0.3.0 CLI tarball from the GitHub Release
pnpm add -g https://github.com/KyaniteLabs/DialectOS/releases/download/v0.3.0/dialectos-cli-0.3.0.tgz

# Or use a local source checkout
pnpm install --froz