From d1aa4821ea2a0aa49d5199f965334de842ad462d Mon Sep 17 00:00:00 2001
From: Cristian Gutierrez <kiyoma19@gmail.com>
Date: Wed, 12 Aug 2026 12:40:08 +0200
Subject: [PATCH] fix(docs): Spanish strings were showing on the English docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs are English-only, but Spanish had leaked into the chrome a reader
sees. Not the prose, which is written in English: defaults and labels buried in
components, which is why review kept missing them.

What was showing in production:
- "limitaciones conocidas" as the heading of the limits card on /docs/models.
  It is the default title of <LimitationsCard>, used whenever the tag carries
  no explicit one.
- "Copiar" on every code block, "Copiado" after clicking, "¡Copiado al
  portapapeles!" in the toast and "Error al copiar" on failure.
- "rate limits por API key", "Paralelo máximo", "concurrentes", "tokens / min
  por modelo" and "requests / min por modelo" in the rate limits card.

The card's default title and the rate-limit labels each live in TWO places that
have to agree: the component a person reads and the extractor that feeds
/api/docs and the Discord bot. Both sides are changed together, and the fixture
that pins the extractor's output is updated with them.

A guard is added over the docs components and the layout so this cannot come
back. It only inspects strings a reader can see, not comments: the repo keeps
Spanish comments in the layouts and styles on purpose. DocsTopBar.astro and
ApiReference.astro are exempt because their Spanish is the translated chrome of
/es/docs/api, which is the point.

Verified by mutation: restoring any of the three Spanish strings, or letting
the component and the extractor drift apart, makes the suite fail.
---
 src/components/docs/CodeBlock.astro         |  4 +-
 src/components/docs/LimitationsCard.astro   |  2 +-
 src/components/docs/RateLimits.astro        | 10 +--
 src/layouts/Docs.astro                      | 14 ++--
 src/lib/__fixtures__/ratelimits.expected.md |  8 +-
 src/lib/mdxToText.test.ts                   |  8 +-
 src/lib/mdxToText.ts                        | 10 +--
 src/tests/layouts/docsCopyIsEnglish.test.ts | 93 +++++++++++++++++++++
 8 files changed, 121 insertions(+), 28 deletions(-)
 create mode 100644 src/tests/layouts/docsCopyIsEnglish.test.ts

diff --git a/src/components/docs/CodeBlock.astro b/src/components/docs/CodeBlock.astro
index e7367f1..d6fd758 100644
--- a/src/components/docs/CodeBlock.astro
+++ b/src/components/docs/CodeBlock.astro
@@ -33,13 +33,13 @@ const uid = Math.random().toString(36).slice(2);
     <span class="font-mono text-[10px] text-violet-400/80 uppercase tracking-widest">{langLabel}</span>
     <button
       class="copy-btn flex items-center gap-1.5 rounded-md px-2 py-1 text-[10px] font-mono uppercase tracking-wider text-neutral-500 transition-colors hover:text-neutral-200 hover:bg-neutral-800/60"
-      aria-label={`Copiar ${langLabel} código`}
+      aria-label={`Copy ${langLabel} code`}
     >
       <svg xmlns="http://www.w3.org/2000/svg" class="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
         <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
         <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" />
       </svg>
-      <span class="copy-label">Copiar</span>
+      <span class="copy-label">Copy</span>
     </button>
   </div>
   <pre class="whitespace-pre"><code>{code}</code></pre>
diff --git a/src/components/docs/LimitationsCard.astro b/src/components/docs/LimitationsCard.astro
index f9b504b..7838013 100644
--- a/src/components/docs/LimitationsCard.astro
+++ b/src/components/docs/LimitationsCard.astro
@@ -9,7 +9,7 @@ interface Props {
   items: Limitation[];
 }
 
-const { title = 'limitaciones conocidas', items } = Astro.props;
+const { title = 'known limitations', items } = Astro.props;
 ---
 
 <div class="rounded-xl border border-amber-900/40 bg-amber-950/20 p-6 mb-14 not-prose">
diff --git a/src/components/docs/RateLimits.astro b/src/components/docs/RateLimits.astro
index 66d22ee..f14963e 100644
--- a/src/components/docs/RateLimits.astro
+++ b/src/components/docs/RateLimits.astro
@@ -13,7 +13,7 @@ const { perKey, tokensPerMinuteByModel, requestsPerMinuteByModel, windowedModels
 
 <div class="rounded-xl border border-neutral-800/60 bg-[#0a0a0a] p-6 mb-6">
   <p class="font-mono text-[10px] text-violet-400 uppercase tracking-widest mb-4">
-    rate limits por API key
+    rate limits per API key
   </p>
   <dl class="grid gap-3 sm:grid-cols-2">
     <div class="flex items-baseline justify-between gap-4 font-mono text-xs">
@@ -21,8 +21,8 @@ const { perKey, tokensPerMinuteByModel, requestsPerMinuteByModel, windowedModels
       <dd class="text-neutral-200 text-right">{perKey.requestsPerMinute} rpm</dd>
     </div>
     <div class="flex items-baseline justify-between gap-4 font-mono text-xs">
-      <dt class="text-neutral-500 uppercase tracking-wider">Paralelo máximo</dt>
-      <dd class="text-neutral-200 text-right">{perKey.maxParallel} concurrentes</dd>
+      <dt class="text-neutral-500 uppercase tracking-wider">Max parallel</dt>
+      <dd class="text-neutral-200 text-right">{perKey.maxParallel} concurrent</dd>
     </div>
   </dl>
 </div>
@@ -67,7 +67,7 @@ const { perKey, tokensPerMinuteByModel, requestsPerMinuteByModel, windowedModels
 
 <div class="rounded-xl border border-neutral-800/60 bg-[#0a0a0a] p-6 mb-6">
   <p class="font-mono text-[10px] text-violet-400 uppercase tracking-widest mb-4">
-    tokens / min por modelo
+    tokens / min per model
   </p>
   <dl class="grid gap-3 sm:grid-cols-2">
     {
@@ -83,7 +83,7 @@ const { perKey, tokensPerMinuteByModel, requestsPerMinuteByModel, windowedModels
 
 <div class="rounded-xl border border-neutral-800/60 bg-[#0a0a0a] p-6 mb-14">
   <p class="font-mono text-[10px] text-violet-400 uppercase tracking-widest mb-4">
-    requests / min por modelo
+    requests / min per model
   </p>
   <dl class="grid gap-3 sm:grid-cols-2">
     {
diff --git a/src/layouts/Docs.astro b/src/layouts/Docs.astro
index 3f1c5be..ab9ea68 100644
--- a/src/layouts/Docs.astro
+++ b/src/layouts/Docs.astro
@@ -278,7 +278,7 @@ const searchData = [
     </div>
 
     <!-- Copy toast notification -->
-    <div class="copy-toast" id="copy-toast">¡Copiado al portapapeles!</div>
+    <div class="copy-toast" id="copy-toast">Copied to clipboard</div>
 
     <script define:vars={{ searchData }} is:inline>
       // Search: filters by title, description and headings. No dependencies and
@@ -477,22 +477,22 @@ const searchData = [
         const button = document.createElement('button');
         button.type = 'button';
         button.className = 'copy-btn';
-        button.setAttribute('aria-label', `Copiar ${lang.label}`);
-        button.innerHTML = '<span class="copy-label">Copiar</span>';
+        button.setAttribute('aria-label', `Copy ${lang.label}`);
+        button.innerHTML = '<span class="copy-label">Copy</span>';
         button.addEventListener('click', async () => {
           const text = pre.textContent || '';
           try {
             await navigator.clipboard.writeText(text);
             const copyLabel = button.querySelector('.copy-label');
-            if (copyLabel) copyLabel.textContent = 'Copiado!';
-            showCopyToast('¡Copiado al portapapeles!');
+            if (copyLabel) copyLabel.textContent = 'Copied';
+            showCopyToast('Copied to clipboard');
             window.setTimeout(() => {
               const resetLabel = button.querySelector('.copy-label');
-              if (resetLabel) resetLabel.textContent = 'Copiar';
+              if (resetLabel) resetLabel.textContent = 'Copy';
             }, 1500);
           } catch (err) {
             console.error('copy failed', err);
-            showCopyToast('Error al copiar');
+            showCopyToast('Copy failed');
           }
         });
 
diff --git a/src/lib/__fixtures__/ratelimits.expected.md b/src/lib/__fixtures__/ratelimits.expected.md
index 5559207..f10224d 100644
--- a/src/lib/__fixtures__/ratelimits.expected.md
+++ b/src/lib/__fixtures__/ratelimits.expected.md
@@ -1,7 +1,7 @@
-**rate limits por API key**
+**rate limits per API key**
 
 - Requests / min: 60 rpm
-- Paralelo máximo: 5 concurrentes
+- Max parallel: 5 concurrent
 
 **glm5.2 · premium tier limits**
 
@@ -12,13 +12,13 @@
 
 400M tokens per rolling 4 hours is the limit a heavy coding-agent run reaches first, well before the allowance. Once you hit it, glm5.2 requests are rejected until the window slides forward: it is a rolling window, not a daily reset. The allowance counter goes back to zero when your billing period starts, and if you upgrade part-way into a period that first allowance is prorated to the share of the period you paid for.
 
-**tokens / min por modelo**
+**tokens / min per model**
 
 - deepseek-v4-flash: 1.5M tpm
 - mimo-v2.5: 1.5M tpm
 - qwen3.6: 1.5M tpm
 - gemma4: 1.5M tpm
 
-**requests / min por modelo**
+**requests / min per model**
 
 - rerank: 1000 rpm
\ No newline at end of file
diff --git a/src/lib/mdxToText.test.ts b/src/lib/mdxToText.test.ts
index e4ac8b1..b1a17b0 100644
--- a/src/lib/mdxToText.test.ts
+++ b/src/lib/mdxToText.test.ts
@@ -97,7 +97,7 @@ describe('mdxToText rate limits', () => {
       ],
     });
     expect(out).toContain('- Requests / min: 120 rpm');
-    expect(out).toContain('- Paralelo máximo: 8 concurrentes');
+    expect(out).toContain('- Max parallel: 8 concurrent');
     expect(out).toContain('- foo: 2M tpm');
     expect(out).toContain('- bar: 500 rpm');
     expect(out).toContain('**baz · premium tier limits**');
@@ -110,7 +110,7 @@ describe('mdxToText rate limits', () => {
   it('defaults to the same numbers <RateLimits /> renders', async () => {
     const out = await mdxToText(input);
     expect(out).toContain('- Requests / min: 60 rpm');
-    expect(out).toContain('- Paralelo máximo: 5 concurrentes');
+    expect(out).toContain('- Max parallel: 5 concurrent');
     // glm5.2 is gated by the window, not by a per-minute rate, and the docs
     // had no row for it at all while the model was already being served.
     expect(out).toContain('- Rolling 4h window: 400M tokens');
@@ -124,8 +124,8 @@ describe('mdxToText rate limits', () => {
       requestsPerMinuteByModel: [],
       windowedModels: [],
     });
-    expect(out).not.toContain('tokens / min por modelo');
-    expect(out).not.toContain('requests / min por modelo');
+    expect(out).not.toContain('tokens / min per model');
+    expect(out).not.toContain('requests / min per model');
     expect(out).not.toContain('premium tier limits');
   });
 });
diff --git a/src/lib/mdxToText.ts b/src/lib/mdxToText.ts
index 8dcc954..7fa70bf 100644
--- a/src/lib/mdxToText.ts
+++ b/src/lib/mdxToText.ts
@@ -285,7 +285,7 @@ function modelCardToMd(node: MdxNode): string {
 }
 
 function limitationsCardToMd(node: MdxNode): string {
-  const title = String(getAttr(node, 'title') ?? 'limitaciones conocidas');
+  const title = String(getAttr(node, 'title') ?? 'known limitations');
   const items = (getAttr(node, 'items') as Array<{ title?: string; body?: string }> | undefined) || [];
 
   const lines: string[] = [`### ${title}`, ''];
@@ -346,10 +346,10 @@ function calloutToMd(node: MdxNode): string {
 
 function rateLimitsToMd(config: RateLimitsConfig): string {
   const lines = [
-    '**rate limits por API key**',
+    '**rate limits per API key**',
     '',
     `- Requests / min: ${config.perKey.requestsPerMinute} rpm`,
-    `- Paralelo máximo: ${config.perKey.maxParallel} concurrentes`,
+    `- Max parallel: ${config.perKey.maxParallel} concurrent`,
     '',
   ];
   for (const m of config.windowedModels) {
@@ -366,12 +366,12 @@ function rateLimitsToMd(config: RateLimitsConfig): string {
     );
   }
   if (config.tokensPerMinuteByModel.length) {
-    lines.push('**tokens / min por modelo**', '');
+    lines.push('**tokens / min per model**', '');
     for (const m of config.tokensPerMinuteByModel) lines.push(`- ${m.model}: ${m.label}`);
     lines.push('');
   }
   if (config.requestsPerMinuteByModel.length) {
-    lines.push('**requests / min por modelo**', '');
+    lines.push('**requests / min per model**', '');
     for (const m of config.requestsPerMinuteByModel) lines.push(`- ${m.model}: ${m.label}`);
     lines.push('');
   }
diff --git a/src/tests/layouts/docsCopyIsEnglish.test.ts b/src/tests/layouts/docsCopyIsEnglish.test.ts
new file mode 100644
index 0000000..00bebad
--- /dev/null
+++ b/src/tests/layouts/docsCopyIsEnglish.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+/**
+ * The docs are English-only, and Spanish had leaked into what a reader sees.
+ *
+ * Not into the prose, which is written in English, but into the CHROME: the
+ * copy button said "Copiar", the toast "¡Copiado al portapapeles!", the rate
+ * limits card "Paralelo máximo / concurrentes", and a `<LimitationsCard>` with
+ * no explicit title fell back to "limitaciones conocidas". None of it was
+ * caught by review because the surrounding code and content were English; the
+ * strings were defaults and labels buried in components.
+ *
+ * The Spanish that legitimately remains is out of scope here: comments, which
+ * no reader sees, and the `es` branch of DocsTopBar, which is the translated
+ * chrome of /es/docs/api.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const componentsDir = resolve(here, '../../components/docs');
+
+/** Words that only appear in Spanish, and never inside a URL or identifier. */
+const SPANISH = [
+  'copiar',
+  'copiado',
+  'portapapeles',
+  'limitaciones',
+  'conocidas',
+  'paralelo',
+  'concurrentes',
+  'por modelo',
+  'por api key',
+  'anterior',
+  'siguiente',
+  'en esta página',
+  'búsqueda',
+  'página',
+];
+
+/**
+ * Only strings a reader can end up seeing: quoted literals and text between
+ * tags. Comments are deliberately excluded, since the repo keeps Spanish ones
+ * in the layouts and styles on purpose.
+ */
+function visibleText(source: string): string {
+  return source
+    .split('\n')
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join('\n');
+}
+
+/** Files that legitimately hold Spanish copy for the /es route. */
+const BILINGUAL = ['DocsTopBar.astro', 'ApiReference.astro'];
+
+const files = [
+  ...readdirSync(componentsDir)
+    .filter((f) => f.endsWith('.astro'))
+    .map((f) => [`components/docs/${f}`, resolve(componentsDir, f)] as const),
+  ['layouts/Docs.astro', resolve(here, '../../layouts/Docs.astro')] as const,
+  ['lib/mdxToText.ts', resolve(here, '../../lib/mdxToText.ts')] as const,
+];
+
+describe('the docs chrome is in English', () => {
+  for (const [label, path] of files) {
+    it(`${label} shows no Spanish to the reader`, () => {
+      const text = visibleText(readFileSync(path, 'utf-8')).toLowerCase();
+      // These two carry the translated chrome and metadata of /es/docs/api on
+      // purpose, in an `es` branch beside the `en` one. Their Spanish is the
+      // point, not a leak.
+      if (BILINGUAL.some((f) => label.endsWith(f))) return;
+      const found = SPANISH.filter((w) => text.includes(w));
+      expect(found, `${label}: ${found.join(', ')}`).toEqual([]);
+    });
+  }
+});
+
+/**
+ * The card's default title lives in two places that have to agree: the
+ * component a person reads and the extractor that feeds /api/docs. They drifted
+ * once already over the rate limits, which is why rateLimits.ts exists.
+ */
+describe('LimitationsCard default title', () => {
+  it('matches between the component and the text extractor', () => {
+    const component = readFileSync(resolve(componentsDir, 'LimitationsCard.astro'), 'utf-8');
+    const extractor = readFileSync(resolve(here, '../../lib/mdxToText.ts'), 'utf-8');
+    const fromComponent = /title = '([^']+)'/.exec(component)?.[1];
+    const fromExtractor = /getAttr\(node, 'title'\) \?\? '([^']+)'/.exec(extractor)?.[1];
+    expect(fromComponent).toBeDefined();
+    expect(fromExtractor).toBe(fromComponent);
+  });
+});