<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 — operating system for multi-dialect / multi-agent product work. Best for builders running multi-agent product and language workflows. Keywords: multi-agent OS, dialect, product agent orchestration.

**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-9.15.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 --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-missing ./locales/en.json ./locales/es.json

# List all supported dialects
dialectos dialects list
```

### From source

```bash
git clone https://github.com/KyaniteLabs/DialectOS.git
cd DialectOS
pnpm install
pnpm build
pnpm test        # 662+ tests passing
```

---

## 🛠️ MCP Tools

### Markdown Translation (4 tools)
| Tool | Description |
|------|-------------|
| `translate_markdown` | Translate while preserving tables, code blocks, links |
| `extract_translatable` | Extract only translatable text from markdown |
| `translate_api_docs` | Translate API docs with table cell-level translation |
| `create_bilingual_doc` | Side-by-side bilingual documents |

### i18n Operations (6 tools)
| Tool | Description |
|------|-------------|
| `detect_missing_keys` | Compare locale files for missing keys |
| `translate_missing_keys` | Auto-translate missing keys |
| `batch_translate_locales` | Batch translate to multiple dialects |
| `manage_dialect_variants` | Create dialect-specific variants |
| `check_formality` | Check tú vs usted consistency |
| `apply_gender_neutral` | Apply gender-neutral language |

### Translation (7 tools)
| Tool | Description |
|------|-------------|
| `translate_text` | Translate with semantic context, grammar profiles, and quality contracts |
| `detect_dialect` | Detect dialect from sample text |
| `translate_code_comment` | Translate comments, preserve code |
| `translate_readme` | Full README translation pipeline |
| `search_glossary` | Search 300+ source-attributed glossary terms |
| `list_dialects` | List all 25 supported dialects |
| `research_regional_term` | Research source-backed regional lexeme proposals without mutating runtime data |

---

## 📦 Packages

| Package | Version | Description | Tests |
|---------|---------|-------------|-------|
| [`@dialectos/mcp`](packages/mcp) | `0.3.0` | 17 MCP tools (stdio server) | 93 |
| [`@dialectos/cli`](packages/cli) | `0.3.0` | CLI: translate, validate, corpus, benchmark, glossary | 569 |
| [`@dialectos/providers`](packages/providers) | `0.3.0` | LLM, DeepL, LibreTranslate, MyMemory with circuit breaker + corpus | 152 |
| [`@dialectos/security`](packages/security) | `0.3.0` | Rate limiting, SSRF protection, sanitization | 68 |
| [`@dialectos/types`](packages/types) | `0.3.0` | Shared TypeScript types + glossary, profile, certification, and quality data | 54 |
| [`@dialectos/locale-utils`](packages/locale-utils) | `0.3.0` | Locale file diff/merge utilities | 55 |
| [`@dialectos/markdown-parser`](packages/markdown-parser) | `0.3.0` | Structure-preserving markdown parser | 74 |

**662+ tests across 7 packages plus docs contracts, demo-server contracts, and static-hardening checks**

---

## 🛡️ Security & Quality

DialectOS has undergone adversarial security hardening:

- **18 CVEs resolved** via dependency overrides
- **SSRF protection** on all provider endpoints
- **Circuit breaker** with half-open probe locks
- **Atomic checkpoint writes** with schema versioning
- **HTML injection detection** in translated output
- **Semantic drift scoring** — catches "looks valid but meaning changed"
- **Provider capability negotiation** — validates language support before API calls
- **Chaos harness** for deterministic resilience testing

See [`SECURITY.md`](SECURITY.md) for details.

---

## 🎨 Supported Dialects

| Code | Region | Example Difference |
|------|--------|-------------------|
| `es-ES` | Spain | *"Coche"* (car), *"Ordenador"* (computer) |
| `es-MX` | Mexico | *"Carro"*, *"Computadora"* |
| `es-AR` | Argentina | *"Auto"*, *"Computadora"*, *"Che"* |
| `es-CO` | Colombia | *"Carro"*, *"Computador"*, *"Chévere"* |
| `es-CL` | Chile | *"Auto"*, *"Computadora"*, *"Caleta"* |
| `es-PE` | Peru | *"Carro"*, *"Computadora"*, *"Pe"* |
| `es-VE` | Venezuela | *"Carro"*, *"Computadora"*, *"Chamo"* |
| `es-UY` | Uruguay | *"Auto"*, *"Computadora"*, *"Bo"* |
| `es-GQ` | Equatorial Guinea | *"Carro"*, *"Camisola"*, *"Bacalao"* |
| `es-US` | United States | *"Carro"*, *"Computadora"*, *"Pocha"* |
| `es-PH` | Philippines (Chavacano) | *"Carro"*, *"Jendeh"*, *"Kame"* |
| `es-BZ` | Belize | *"Carro"*, *"Breki"*, *"Kriol"* |
| `es-AD` | Andorra | *"Carro"*, *"Madriu"*, *"Caldea"* |

...and 12 more. Full list via `dialectos dialects list`.

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                            │
│              (Claude Desktop / Cursor / etc.)                │
└──────────────────────┬──────────────────────────────────────┘
                       │ stdio
┌──────────────────────▼──────────────────────────────────────┐
│                   @dialectos/mcp                               │
│              17 tools • JSON-RPC over stdio                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                   @dialectos/cli                               │
│   translate • validate • corpus • benchmark • glossary     │
│   ├─ Policy profiles (strict/balanced/permissive)           │
│   ├─ Quality gates (token/glossary/structure/semantic)      │
│   ├─ Translation corpus + auto-glossary                     │
│   └─ Checkpoint resumption + telemetry                      │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                @dialectos/providers                            │
│   ┌─────────┐  ┌─────────────────┐  ┌─────────────────┐    │
│   │   LLM   │  │     DeepL       │  │ Libre/MyMemory │   │
│   │ Primary │  │ Paid fallback   │  │ Generic fallback│    │
│   └─────────┘  └─────────────────┘  └─────────────────┘    │
│        │                │                    │              │
│        └────────────────┴────────────────────┘              │
│              Circuit Breaker + Rate Limiter                  │
└─────────────────────────────────────────────────────────────┘
```

---

## 📊 Quality Gates

Every translation passes through 4 quality dimensions:

```
Quality Score = tokenIntegrity×25% + glossaryFidelity×30% + structureIntegrity×20% + semanticSimilarity×25%
```

| Gate | What it checks | Example failure |
|------|---------------|-----------------|
| **Token Integrity** | Protected terms preserved | "Kyanite Labs" → "Cianita Labs" |
| **Glossary Fidelity** | Enforced terminology used | "API" → "Interfaz" (when glossary says "API") |
| **Structure Integrity** | Markdown structure intact | Missing code fence, broken table |
| **Semantic Similarity** | Meaning not drifted | "API is down" → "Hello world" |

---

## ❓ FAQ

**What is DialectOS?**
DialectOS is an open-source translation engine for Spanish regional dialects. It runs as
an MCP server (for AI assistants like Claude) and a CLI tool for developers.

**How is DialectOS different from Google Translate?**
Google Translate treats Spanish as one language. DialectOS understands 25 regional
variants, preserves markdown structure, enforces glossaries, and applies quality gates
that catch errors before they reach users.

**What are Spanish dialects?**
Spanish varies significantly by country. Mexican Spanish uses "carro" for car; Spain uses
"coche"; Argentina uses "auto". DialectOS handles these differences automatically.

**Does DialectOS work with ChatGPT / Claude?**
Yes. DialectOS is an MCP server, so Claude Desktop, Cursor, Windsurf, and other MCP
clients can use its 17 translation tools natively.

**Is DialectOS free?**
Yes. DialectOS v0.3.0 is released under Apache-2.0. See [LICENSE](LICENSE) for details.

**What is MCP?**
Model Context Protocol is an open standard that lets AI assistants use external tools.
DialectOS exposes 17 translation tools through MCP so AI agents can translate natively.

**Can I use DialectOS for commercial projects?**
Yes. Apache-2.0 allows commercial use, modification, and redistribution subject to the license terms. See [LICENSE](LICENSE) for details.

**How accurate is the translation?**
DialectOS applies 4 quality gates (token integrity, glossary fidelity, structure integrity,
semantic similarity) and adversarial tests. Automated tests verify correctness across dialects.

## 🏷️ Badges

Add this badge to your project if you use DialectOS for translation:

```markdown
[![Translated with DialectOS](https://img.shields.io/badge/translated%20with-DialectOS-d89b2b)](https://github.com/KyaniteLabs/DialectOS)
```

## ⚡ GitHub Action

Validate Spanish translations in CI on every pull request:

```yaml
- uses: KyaniteLabs/DialectOS/action  # Planned — version pinning unavailable until first release
  with:
    dialect: es-MX
    source-dir: locales/en
    target-patterns: 'locales/es-MX/*.json'
    fail-on-blocking: true
```

Multi-dialect matrix:

```yaml
strategy:
  matrix:
    dialect: [es-ES, es-MX, es-AR, es-CO]
steps:
  - uses: KyaniteLabs/DialectOS/action  # Planned — version pinning unavailable until first release
    with:
      dialect: ${{ matrix.dialect }}
      fail-on-blocking: true
```

See [`docs/github-action.md`](docs/github-action.md) for full configuration options.

---

## 🤝 Contributing

We welcome contributors! See [`CONTRIBUTING.md`](CONTRIBUTING.md) for:
- Setting up your development environment
- Running the test suite
- Submitting pull requests
- Code style guidelines

**Good first issues** are tagged with `good first issue` — perfect for newcomers.

---

## 📋 Roadmap

See [`ROADMAP.md`](ROADMAP.md) for upcoming features including:
- Portuguese dialect support (pt-BR, pt-PT)
- Real-time collaborative translation
- Custom provider plugins
- OpenAI-compatible, Anthropic-compatible, and LM Studio local gateways via `LLM_API_URL`/`LM_STUDIO_URL` + `LLM_MODEL` + `LLM_API_FORMAT`
- VS Code extension

---

## 📄 License

Apache-2.0 — see [`LICENSE`](LICENSE) for details.

---

<div align="center">

Made with ❤️ by KyaniteLabs and contributors.

**Star ⭐ this repo if it helps your project!**

</div>

---

## Part of KyaniteLabs

More from [KyaniteLabs](https://kyanitelabs.tech). Related projects:

- **[mcp-video](https://github.com/KyaniteLabs/mcp-video)** — guardrailed video-editing MCP server for AI agents
- **[Epoch](https://github.com/KyaniteLabs/Epoch)** — time-estimation MCP server (PERT) for AI agents
- **[checkyourself](https://github.com/KyaniteLabs/checkyourself)** — local-first production-readiness checks for AI-built code

→ More at **[kyanitelabs.tech](https://kyanitelabs.tech)**

<!-- s-plus-geo:start -->

## What is DialectOS?

**DialectOS** is a **operating system for multi-dialect / multi-agent product work** that helps **builders running multi-agent product and language workflows** **coordinate dialect-aware agent operations with clear product surfaces**.

| | |
| --- | --- |
| **Product** | DialectOS |
| **Category** | operating system for multi-dialect / multi-agent product work |
| **Best for** | builders running multi-agent product and language workflows |
| **Not** | a general chat UI |
| **Source** | [GitHub](https://github.com/KyaniteLabs/DialectOS) · [Forgejo](https://git.kyanitelabs.tech/KyaniteLabs/DialectOS) |
| **Keywords** | multi-agent OS, dialect, product agent orchestration |

## Who it's for

- Primary: builders running multi-agent product and language workflows
- Use when you need to coordinate dialect-aware agent operations with clear product surfaces
- Skip if you need a general chat UI

## FAQ

### What is DialectOS?

DialectOS is a operating system for multi-dialect / multi-agent product work. It helps builders running multi-agent product and language workflows coordinate dialect-aware agent operations with clear product surfaces.

### Who should use DialectOS?

builders running multi-agent product and language workflows.

### How is DialectOS different?

Unlike single-agent chat apps, DialectOS is built for multi-dialect product operations.

### Is DialectOS production software?

Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use.

## Status

- Maintained as of 2026 on the default branch
- Prefer release tags when pinning dependencies
- Report issues on the canonical remote listed above

## Agent surface

- Coding agents: read this README first, then repo docs/`AGENTS.md` if present
- Prefer machine-readable briefs (`llms.txt`) when the repo ships one
- MCP or skill entrypoints are documented in-repo when applicable

## Contributing

Issues and PRs welcome on the canonical remote. Keep public docs free of secrets and machine-local paths.

## License

See [LICENSE](LICENSE) in this repository (or package metadata if license is package-only).


## Table of contents

- [What is it?](#what-is-dialectos)
- [FAQ](#faq)
- [Status](#status)

<!-- s-plus-geo:end -->