@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/training-data/references/synthesis-dedup-quality.md

@@ -0,0 +1,134 @@
+# Synthesis, dedup, decontamination, quality, licensing
+
+Depth overflow for SKILL.md §3–§7. Library versions and, above all, model licenses change
+monthly — verify at author time; nothing here is a standing legal fact.
+
+## Synthetic data
+
+**Self-Instruct**: hand-write a small seed set of diverse instructions+responses, prompt a
+strong model to generate many more conditioned on the seeds, then filter for validity, dedup,
+and difficulty. **Evol-Instruct**: iteratively rewrite each instruction to be harder
+(add constraints, deepen, broaden) so the corpus spans a difficulty gradient. **AI feedback /
+UltraFeedback-style**: have a model rate candidate responses on axes (helpfulness, honesty,
+correctness) to build preference pairs.
+
+### distilabel skeleton (Argilla / Hugging Face, v1.x — verify)
+
+```python
+from distilabel.pipeline import Pipeline
+from distilabel.steps import LoadDataFromDicts
+from distilabel.steps.tasks import TextGeneration
+# LLM client import paths shift between releases — check current distilabel docs.
+
+with Pipeline(name="self-instruct") as pipe:
+    seeds = LoadDataFromDicts(data=[{"instruction": "Explain X."}, ...])
+    gen   = TextGeneration(llm=...)      # plug an LLM client
+    seeds >> gen
+
+distiset = pipe.run(parameters={...})
+distiset.push_to_hub("me/synthetic-sft")   # pushes data + the pipeline definition + a card
+```
+
+Distilabel serializes the whole pipeline to YAML/JSON and (on push) writes it into the dataset
+card, so a run is reproducible. Output is a `Distiset` (a `datasets.DatasetDict` variant).
+
+### Distillation licensing trap (do this before generating)
+
+Training on *another model's outputs* is governed by that model/provider's terms:
+
+- **Proprietary API outputs** may be contractually barred from training competing models — read
+  the current provider ToS, not a blog.
+- **Open-weight licenses** vary and are **not** all OSI-open: Llama ships under the Meta Llama
+  Community License (with acceptable-use + naming/derivative terms), Gemma has custom Google
+  terms, some models (e.g. Codestral-class) are non-production/research-only, and Qwen license
+  terms vary by size. **Never state a license as bare fact** — open the specific model card,
+  licenses change.
+- Record per-example provenance (which model/source produced it) so an audit can trace it.
+
+## Deduplication
+
+Exact dedup: hash normalized text, drop collisions. Near-dup (the one that matters) —
+**MinHash + LSH** over token/char shingles:
+
+```python
+from datasketch import MinHash, MinHashLSH
+
+def minhash(text, num_perm=128, k=5):
+    m = MinHash(num_perm=num_perm)
+    toks = text.split()
+    for i in range(len(toks) - k + 1):
+        m.update(" ".join(toks[i:i+k]).encode())
+    return m
+
+lsh, keep = MinHashLSH(threshold=0.8, num_perm=128), []
+for i, ex in enumerate(dataset):
+    mh = minhash(ex["text"])
+    if not lsh.query(mh):            # no near-duplicate already kept
+        lsh.insert(str(i), mh); keep.append(i)
+dedup = dataset.select(keep)
+```
+
+For very large corpora use a batched/distributed dedup (e.g. HF `datatrove`, `text-dedup`)
+rather than an in-memory loop. Tune `threshold` on a sample — too high keeps paraphrase dupes,
+too low deletes legitimately similar-but-distinct examples.
+
+## Decontamination (against eval/benchmark test sets)
+
+Leakage of test items into training inflates your eval — you measure memorization. Remove any
+training row that overlaps a test item, by **n-gram overlap** (the common convention is a long
+n-gram, e.g. 13-gram, exact match; also embed-and-threshold for paraphrased leakage):
+
+```python
+def ngrams(text, n=13):
+    t = text.lower().split()
+    return {" ".join(t[i:i+n]) for i in range(len(t) - n + 1)}
+
+contam = set().union(*(ngrams(x["text"]) for x in eval_set))   # build from EVERY eval you report
+clean  = dataset.filter(lambda ex: ngrams(ex["text"]).isdisjoint(contam))
+```
+
+Decontaminate against **every** benchmark you will quote *and* your own private held-out set —
+including any public dataset you synthesized from, since its test split may be in your training
+mix. `lm-eval-harness` and dataset-curation toolkits ship decontamination utilities; prefer a
+maintained one over hand-rolled for scale.
+
+## Quality filtering
+
+**LIMA** (*Less Is More for Alignment*, arXiv 2305.11206): ~1,000 curated examples produced a
+strong instruction-follower — for teaching **behavior/style/format**, curation and diversity
+beat raw volume. Caveat: LIMA is about *alignment*, not injecting large new *knowledge* — a
+broad domain-knowledge shift still wants scale. Practical filter ladder:
+
+1. **Format/structural** — drop empty/truncated turns, malformed JSON, wrong role order, missing
+   final assistant turn (SFT), identical `chosen`/`rejected` (preference).
+2. **Length** — cut extreme-short and runaway-long outliers (often degenerate/repetitive).
+3. **Dedup + decontam** (above).
+4. **Diversity** — embed and cluster; downsample over-represented intents so one task is not 80%
+   of the set. (Lilac was built for exactly this triage — but its OSS repo was archived
+   ~July 2025 after the Databricks acquisition; **[verify]** before depending on it.)
+5. **Scoring** — reward model or LLM-as-judge rates helpfulness/correctness; keep the top slice.
+   Audit the judge: it has position/length/self-preference biases; spot-check by hand.
+
+Always keep a discarded-rows sample so filtering decisions are reviewable, not a black hole.
+
+## Licensing — two separate questions
+
+1. **Your dataset's license** — what you release the JSONL under, and whether you *may* (you
+   cannot relicense others' data by aggregating it).
+2. **Source-usage restrictions** — the terms attached to where each row came from: scraped-site
+   ToS, the license of any base dataset, and the model-output ToS above. These bind even if you
+   never publish. A `source`/`license` provenance column per row makes an audit tractable.
+
+Write a **data card** (HF dataset README front-matter): license, sources, generation method,
+dedup/decontam done, known biases, intended use.
+
+## Tooling summary
+
+| Tool | Use | Note |
+| --- | --- | --- |
+| distilabel | synthetic data / AI-feedback pipelines | Argilla/HF, v1.x, → `Distiset` |
+| Argilla | human annotation/review UI | vet and label examples |
+| HF `datasets` | load/map/filter/push | the substrate |
+| datatrove / text-dedup | large-scale dedup | when datasketch loop is too small |
+| lm-eval-harness | eval + decontamination utils | report metrics on the clean split |
+| Lilac | dataset exploration/clustering | **OSS archived ~2025-07 [verify]** |

package/skills/shared/translation-l10n/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: translation-l10n
+description: "Use when adding a second or Nth language to a web or app product — i18n plumbing (string extraction, ICU messages, locale routing), fixing broken plurals or date formats, and making a UI survive other languages through right-to-left layout and text expansion. NOT defining the brand's tone in one language (that is `brand-voice`)."
+tags: [i18n, l10n, internationalization, localization, translation, rtl, icu-messageformat]
+recommends: [brand-voice, nextjs, seo-geo, accessibility, content-engine]
+origin: ai-hub
+---
+
+# Translation & localization
+
+You are making a product speak more than one language *correctly* — not word-for-word. The job splits in two, and confusing them is the root cause of "we translated everything but the dates are still American."
+
+- **i18n (internationalization)** = engineering the code so it *can* hold any locale: no hardcoded strings, externalized catalogs, locale-aware formatting, locale routing. Done once.
+- **l10n (localization)** = the per-locale *content* and cultural formatting: the actual translations, plural rules, date/number/currency conventions, RTL layout. Done per language, repeatedly.
+
+Sequence matters: do i18n first. Teams that skip it end up retrofitting string extraction under a launch deadline, which is when concatenation and `count === 1` bugs ship.
+
+## Route out fast
+
+| If the task is really about… | Go to |
+| --- | --- |
+| Inventing the brand's tone/word bank in one language | `../brand-voice/SKILL.md` |
+| App Router structure, React Server Components, data fetching (non-locale) | `../nextjs/SKILL.md` |
+| hreflang strategy, per-country keyword research, geo ranking | `../seo-geo/SKILL.md` |
+| Authoring net-new source copy (landing, article) | `../content-engine/SKILL.md` |
+| General a11y semantics beyond `lang`/`dir`/bidi | `../accessibility/SKILL.md` |
+
+This skill emits the `lang`/`dir`/alternate plumbing and only touches routing where it is locale-specific. It does not author source copy or invent voice — it moves an existing voice across languages.
+
+## Decision: where are you?
+
+| Symptom | Enter |
+| --- | --- |
+| Hardcoded strings live in JSX/components | Phase 1 — internationalize the code |
+| Plurals/gender are wrong in some language | Phase 2 — ICU MessageFormat |
+| Dates/numbers/currency look wrong per locale | Locale-aware formatting (`Intl.*`) |
+| Layout breaks, text overflows, Arabic mirrored wrong | Phase 3 routing + RTL & bidi |
+| "We have the strings, we need them translated" | Phase 4 — translation workflow |
+
+## Phase 1 — internationalize the code
+
+**Externalize every user-facing string to a catalog.** A string in JSX cannot be translated, pseudolocalized, or counted as missing. Move it to a message file keyed by a stable, namespaced ID.
+
+**Key on intent, not on the English text.** `checkout.payButton` survives a copy change; `"Pay now"` as the key breaks every translation the moment marketing edits the English.
+
+```json
+{
+  "checkout": {
+    "payButton": "Pay now",
+    "itemsInCart": "{count, plural, one {# item} other {# items}}"
+  }
+}
+```
+
+**Library choice — pick once:**
+
+| Stack / need | Use | Why |
+| --- | --- | --- |
+| Next.js App Router | `next-intl` | Request-scoped `i18n/request.ts` + `defineRouting()`, React Server Components-native, `localePrefix` strategies |
+| Cross-stack / existing i18next ecosystem | `next-i18next` / `i18next` | Shared catalogs across React Native, backend, plugins |
+| Tiny app, few strings, no plural complexity | `Intl` only | No dependency; you still get correct formatting |
+
+**Never concatenate translated fragments.** Word order is not universal — building a sentence from pieces produces garbage in languages that reorder subject/object/verb.
+
+```tsx
+// Bad — three fragments the translator can never reorder
+<p>{t("youHave")} {count} {t("messages")}</p>
+
+// Good — one message, named/numeric ICU argument
+<p>{t("inbox.summary", { count })}</p>
+// "inbox.summary": "{count, plural, one {You have # message} other {You have # messages}}"
+```
+
+**Configure a fallback locale.** A missing key in `de` should resolve to `en`, never render the raw key or blank. Set the default/source locale as the fallback at config time.
+
+## Phase 2 — ICU MessageFormat correctly
+
+ICU MessageFormat is the cross-library standard for plurals and `select`, powered by CLDR plural categories. Use it for **plurals and gender only** — keep date/number formatting out (next section).
+
+**CLDR defines up to six plural categories. English uses two; you cannot assume singular/plural is enough.**
+
+| Category | Example languages |
+| --- | --- |
+| `one`, `other` | English, German, Spanish |
+| `one`, `few`, `many`, `other` | Russian, Polish, Czech |
+| `zero`, `one`, `two`, `few`, `many`, `other` | Arabic (all six) |
+| `other` only | Chinese, Japanese, Korean |
+
+```tsx
+// Bad — correct only for English-like 2-form languages
+const label = count === 1 ? "item" : "items";
+
+// Good — ICU resolves the right CLDR category per locale
+// "cart.items": "{count, plural, one {# item} other {# items}}"
+// Russian catalog supplies one/few/many/other; the call site never changes.
+```
+
+**Every `plural`, `selectordinal`, and `select` block REQUIRES an `other` clause** — it is the mandatory fallback; without it the message is invalid and the formatter throws.
+
+```icu
+{gender, select, female {She replied} male {He replied} other {They replied}}
+{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} place
+```
+
+**Wrap the formatter in try/catch and fall back to the key.** A malformed ICU string from a translator throws at runtime — returning the key keeps the UI alive while you log the error.
+
+```ts
+function format(key: string, args?: Record<string, unknown>) {
+  try {
+    return formatter.format(messages[key], args);
+  } catch (err) {
+    console.error(`ICU format failed for "${key}"`, err);
+    return key; // visible, non-crashing fallback
+  }
+}
+```
+
+See `references/icu-cookbook.md` for nested plural+select, escaping `'` and `{`, and per-language plural-category tables.
+
+## Locale-aware formatting
+
+Dates, numbers, and currency belong to `Intl.*`, **not** inside ICU messages and never string-concatenated. These read CLDR data, so `de-DE` renders `1.000,50` while `en-US` renders `1,000.50` — for free.
+
+```ts
+new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(1000.5);
+// "1.000,50 €"
+
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(new Date());
+// "2026年6月2日"
+
+new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(-1, "day");
+// "ayer"
+
+new Intl.ListFormat("en", { type: "conjunction" }).format(["a", "b", "c"]);
+// "a, b, and c"
+
+new Intl.PluralRules("ar").select(3); // "few"  — drives non-ICU plural logic
+```
+
+Rule: if you typed a `/`, `,`, `.`, `$`, or `%` into a translated string, you have a bug. Format with `Intl`.
+
+## Phase 3 — locale routing & rendering
+
+For Next.js App Router with `next-intl`, route locale through a `[locale]` segment. Defer all non-locale framework detail to `../nextjs/SKILL.md`.
+
+```ts
+// routing.ts
+import { defineRouting } from "next-intl/routing";
+
+export const routing = defineRouting({
+  locales: ["en", "es", "ar"],
+  defaultLocale: "en",
+  localePrefix: "as-needed", // 'always' | 'as-needed' | 'never'
+});
+```
+
+`localePrefix`: `always` (`/en/...`, `/es/...`), `as-needed` (default locale unprefixed), or `never` (locale via cookie/header only). Pick based on your SEO needs — defer the ranking call to `../seo-geo/SKILL.md`.
+
+**Add `generateStaticParams` on the `[locale]` segment** so each locale renders statically. Set `lang` *and* `dir` on `<html>` — `dir` is what flips the layout.
+
+```tsx
+export function generateStaticParams() {
+  return routing.locales.map((locale) => ({ locale }));
+}
+
+export default function RootLayout({ children, params: { locale } }) {
+  const dir = locale === "ar" || locale === "he" ? "rtl" : "ltr";
+  return <html lang={locale} dir={dir}>{children}</html>;
+}
+```
+
+## RTL & bidi
+
+**Set direction with the HTML `dir` attribute on the root, not the CSS `direction` property.** `dir` carries semantic meaning the browser and assistive tech use for bidi; CSS `direction` does not. Then write layout with **CSS logical properties** so one stylesheet serves both directions.
+
+| Physical (don't) | Logical (do) |
+| --- | --- |
+| `margin-left` | `margin-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `text-align: left` | `text-align: start` |
+| `left: 0` | `inset-inline-start: 0` |
+| `border-right` | `border-inline-end` |
+
+These auto-flip with `dir`/`writing-mode`, so RTL needs no separate stylesheet. **Isolate interpolated user content** (names, IDs) with `<bdi>` or `unicode-bidi: isolate` so a Hebrew username doesn't scramble surrounding LTR text.
+
+See `references/rtl-and-bidi.md` for the full mapping, which icons to mirror vs. not, and RTL testing.
+
+## Phase 4 — translation workflow
+
+The 2025–2026 pipeline is MT/TM pre-fill → LLM post-edit (MTPE) → human review, governed by a glossary and translation memory.
+
+1. **Freeze the source.** Translating moving copy doubles the work. Lock strings, then hand off.
+2. **Build a glossary/termbase.** Locks product terms ("Workspace", "Boost") to one approved translation per language — keeps terminology consistent and measurably cuts post-edit effort.
+3. **Stand up translation memory (TM).** Reuses approved translations for repeat/near-repeat segments across the product, so you never re-translate or re-pay for the same string.
+4. **MT pre-fill, then LLM post-edit, then human review.** MT/LLM gives a strong first pass; humans review for nuance. Upstream quality (clear source + glossary + style + TM) is what makes the post-edit cheap.
+5. **Preserve placeholders/variables.** `{count}`, `%s`, `<b>…</b>` must survive untouched — validate after every MT/LLM pass.
+
+**Never auto-translate unreviewed:** legal/contract copy (route to `../brand-voice/SKILL.md` and legal review for terms), and brand-voice-critical strings — those need the voice carried deliberately, not machine-flattened.
+
+## Testing
+
+- [ ] **Pseudolocalization first.** Transform source strings: accent the letters, pad +30–40% length, wrap in brackets — e.g. `[Ŝéttîñgś……]`. Surfaces hardcoded strings, truncation/overflow from text expansion, and broken concatenation **before** you hire a single translator.
+- [ ] **Missing-key detection.** Fail CI when a locale lacks a key the source has.
+- [ ] **Longest-language overflow check.** German/Finnish expand most; verify buttons and fixed-width UI survive.
+- [ ] **Per-locale snapshot/visual diff**, including one RTL locale.
+- [ ] **Fallback locale resolves**, never the raw key.
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+| --- | --- | --- |
+| Concatenating translated fragments | Word order differs per language | One ICU message with named args |
+| `count === 1 ? x : y` | Wrong for ~most languages (Russian, Arabic…) | ICU `plural` with CLDR categories |
+| Date/number formats baked into strings | `1,000.50` is wrong in de-DE | `Intl.NumberFormat`/`DateTimeFormat` |
+| `margin-left` everywhere | Doesn't flip for RTL | CSS logical properties |
+| Translating in raw spreadsheets, no TM | Drift, repeat work, lost terms | TM + glossary + a TMS |
+| Machine-translating legal/brand copy unreviewed | Liability + flattened voice | Human/legal + `brand-voice` |
+| No fallback locale | Missing key renders blank/raw | Configure source locale fallback |
+| Using English text as the message key | Copy edit breaks all translations | Stable namespaced key |
+| Missing `other` clause in ICU | Invalid message, formatter throws | Always include `other` |
+| ICU formatting with no try/catch | One bad translation crashes the view | Catch → return key, log |
+| Setting direction via CSS, not HTML `dir` | Loses bidi semantics | `dir` attribute on `<html>` |
+| Assuming all languages expand equally | DE/FI overflow, ZH contracts | Pseudoloc + longest-language test |
+
+## Handoff checklist
+
+**i18n-ready:** no hardcoded user-facing strings · catalog with stable namespaced keys · fallback locale set · all plurals via ICU · all dates/numbers via `Intl` · CSS logical properties · `lang`+`dir` on `<html>` · pseudoloc passes.
+
+**l10n-ready:** glossary/termbase signed off · TM populated · MT→LLM→human pipeline defined · legal/brand strings flagged for human review · per-locale CI checks (missing keys, overflow, RTL snapshot) green.

package/skills/shared/translation-l10n/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — translation-l10n
+
+These cases are run by the ai-hub skill eval harness. `should_trigger` and `should_not_trigger` check routing precision: that locale/translation requests (including non-obvious symptom phrasings and a Spanish prompt) select this skill, while voice (brand-voice), framework wiring (nextjs), ranking strategy (seo-geo), and copy authoring (content-engine) route to the correct sibling instead. The single `capability` case is a rubric, not an executable test — a reviewer (human or model) reads the SKILL.md guidance against an "add Arabic to a React product" scenario and confirms each `must_include` point is covered (i18n-first sequencing, ICU plurals with CLDR `other`, no concatenation, `Intl.*` formatting, RTL via `dir` + logical properties, the glossary/TM/post-edit workflow, pseudoloc + missing-key testing, fallback locale). There is no code to execute — this is a process/knowledge skill, so its rigor lives in the capability rubric rather than a verify.sh.

package/skills/shared/translation-l10n/evals/cases.yaml

@@ -0,0 +1,39 @@
+skill: translation-l10n
+
+should_trigger:
+  - prompt: "We need to ship the app in French and Arabic."
+    why: Core add-a-language request spanning i18n plumbing and RTL — the central use case.
+  - prompt: "Our plural messages are wrong in Russian and Polish — it always shows the singular form."
+    why: ICU/CLDR plural categories; non-obvious symptom that points straight at the count===1 anti-pattern.
+  - prompt: "The German text overflows our buttons and dates still show American format for Spanish users."
+    why: Text-expansion overflow plus Intl date formatting — two localization symptoms phrased as bugs, not as 'i18n'.
+  - prompt: "Set up locale routing with next-intl and generateStaticParams for our App Router."
+    why: Phase 3 locale routing/rendering plumbing — the framework on-ramp this skill owns.
+  - prompt: "Traducir la app al árabe y montar el glosario para los traductores."
+    why: Spanish trigger covering the translation workflow, glossary/termbase, and an RTL language.
+
+should_not_trigger:
+  - prompt: "Define our brand's tone of voice and word bank for our copy."
+    route_to: brand-voice
+    why: Inventing voice in one language; this skill moves an existing voice across languages, it does not author it.
+  - prompt: "How do I fetch data in a Next.js App Router server component?"
+    route_to: nextjs
+    why: General framework wiring unrelated to locale; this skill only touches routing where locale-specific.
+  - prompt: "Plan our hreflang and per-country keyword strategy to rank in Germany."
+    route_to: seo-geo
+    why: Multilingual ranking/geo strategy, not translation or i18n plumbing.
+  - prompt: "Write the English landing page copy for our launch."
+    route_to: content-engine
+    why: Authoring net-new source copy; localization translates existing content, it does not write it.
+
+capability:
+  - scenario: "Add Arabic to our existing React product so it ships correctly."
+    must_include:
+      - i18n-before-l10n sequencing (make the code locale-ready before producing translations)
+      - externalize strings to a catalog with stable namespaced keys; no concatenation of fragments
+      - ICU plural with correct CLDR categories including the mandatory `other` clause (Arabic uses all six)
+      - dates/numbers/currency via `Intl.*`, never baked into strings
+      - RTL via `dir` on `<html>` and CSS logical properties (not CSS `direction`, not `margin-left`)
+      - translation workflow with glossary + translation memory + MT/LLM post-edit + human review
+      - pseudolocalization and missing-key testing before hiring translators
+      - configured fallback locale

package/skills/shared/translation-l10n/references/icu-cookbook.md

@@ -0,0 +1,82 @@
+# ICU MessageFormat cookbook
+
+Lookup recipes for the patterns that don't fit inline in SKILL.md. ICU is for plurals and `select` only — format dates/numbers with `Intl.*`, not inside the message.
+
+## Full-sentence pattern (named args)
+
+Never assemble a sentence from fragments. Put the whole sentence in one message and let the translator reorder freely.
+
+```icu
+{name} shared {count, plural, one {# photo} other {# photos}} with you
+```
+
+The translator owns the entire string, so Japanese or Arabic word order is theirs to set — your call site stays `t("share.summary", { name, count })`.
+
+## Nested plural + select
+
+Combine gender/category selection with pluralization. Each block still needs its own `other`.
+
+```icu
+{gender, select,
+  female {{count, plural, one {She has # follower} other {She has # followers}}}
+  male   {{count, plural, one {He has # follower}  other {He has # followers}}}
+  other  {{count, plural, one {They have # follower} other {They have # followers}}}
+}
+```
+
+## selectordinal — 1st / 2nd / 3rd
+
+`plural` is for cardinals (1 item); `selectordinal` is for ordinals (1st place). English needs `one`/`two`/`few`/`other`; other languages differ.
+
+```icu
+You finished {place, selectordinal,
+  one {#st}
+  two {#nd}
+  few {#rd}
+  other {#th}
+}
+```
+
+## The `#` token
+
+Inside a `plural`/`selectordinal` block, `#` prints the formatted number for the current locale. Outside such a block it is a literal `#`. Don't reuse the count variable name where `#` already does the job.
+
+## Escaping literals
+
+ICU treats `{`, `}`, and `'` as syntax. To print them literally, wrap in single quotes; a doubled `''` prints one apostrophe.
+
+```icu
+This is a literal '{brace}' and an apostrophe '' here.
+```
+
+- `'{brace}'` → renders the text `{brace}` unparsed.
+- `''` → renders `'`.
+- A lone `'` that doesn't open a quoted span is treated as literal in most ICU implementations, but quote it explicitly to be safe.
+
+## Per-language plural categories (quick table)
+
+CLDR rules, summarized. Catalogs for these languages must supply exactly these categories.
+
+| Language | Categories used |
+| --- | --- |
+| English (en), German (de), Spanish (es) | `one`, `other` |
+| French (fr) | `one`, `many`, `other` |
+| Russian (ru) | `one`, `few`, `many`, `other` |
+| Polish (pl) | `one`, `few`, `many`, `other` |
+| Arabic (ar) | `zero`, `one`, `two`, `few`, `many`, `other` |
+| Chinese (zh), Japanese (ja), Korean (ko) | `other` only |
+
+A category your language doesn't use is simply ignored; a category it *does* use but you omitted falls through to `other` — often wrong (e.g. Russian "2 файла" needs `few`, not `other`).
+
+## Skeletons (number/date inside ICU)
+
+ICU supports number/date "skeletons" (`{price, number, ::currency/EUR}`), but prefer formatting outside the message with `Intl` so the format stays in code, reviewable and testable, rather than scattered across translator-edited catalogs. Reserve skeletons for cases where the number is grammatically fused into the sentence.
+
+## Validation before ship
+
+Parse every catalog with your ICU library at build time and assert:
+- every `plural`/`selectordinal`/`select` has an `other` clause,
+- all placeholders present in the source key exist in each translation,
+- no unbalanced `{`/`}`.
+
+A failing parse should break CI, not surface at runtime.

package/skills/shared/translation-l10n/references/rtl-and-bidi.md

@@ -0,0 +1,60 @@
+# RTL & bidi reference
+
+Full depth for right-to-left (Arabic, Hebrew, Persian, Urdu) and bidirectional text. The core rule lives in SKILL.md: set `dir` on `<html>`, write layout with CSS logical properties. This file is the complete mapping plus the judgment calls.
+
+## Physical → logical property mapping
+
+Replace physical properties so one stylesheet flips automatically with `dir`/`writing-mode`.
+
+| Physical | Logical |
+| --- | --- |
+| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` |
+| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` |
+| `left` / `right` | `inset-inline-start` / `inset-inline-end` |
+| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` |
+| `text-align: left` / `right` | `text-align: start` / `end` |
+| `border-top-left-radius` | `border-start-start-radius` |
+| `width` / `height` | `inline-size` / `block-size` |
+| `float: left` | `float: inline-start` |
+
+Flexbox/grid: `flex-start`/`flex-end` and `start`/`end` already follow direction — prefer them over `left`/`right`. Use `justify-content: flex-start`, not absolute positioning, where possible.
+
+## Bidi isolation for interpolated content
+
+User-supplied or locale-foreign text embedded in a sentence can reorder surrounding characters (the "bidi spillover" bug: a Hebrew name pushes an LTR punctuation mark to the wrong side).
+
+- HTML: wrap the interpolated value in `<bdi>` — it isolates the embedded run's direction.
+- CSS: `unicode-bidi: isolate` on the wrapper achieves the same.
+- `dir="auto"` on an input/element lets the browser infer direction from the first strong character — useful for user-generated content fields whose language you don't know.
+
+```html
+<span>@<bdi>{{username}}</bdi> mentioned you</span>
+```
+
+## Mirror vs. don't mirror
+
+When `dir="rtl"`, layout flips — but not every graphic should.
+
+**Mirror** (directional meaning): back/forward arrows, breadcrumb chevrons, progress that advances, list bullets/indentation, send/reply arrows, undo/redo.
+
+**Do NOT mirror** (physical/absolute meaning): media play button (always points to time-forward, conventionally right), clocks, musical notation, checkmarks, logos and brand marks, photos, phone/email/numbers that read LTR even in RTL context, charts with a real x-axis.
+
+Implement icon mirroring with a logical transform scoped to RTL:
+
+```css
+[dir="rtl"] .icon-directional { transform: scaleX(-1); }
+```
+
+Keep a single explicit class for mirrored icons rather than flipping all of them.
+
+## Numbers, dates, and embedded LTR
+
+Numbers and Latin product names stay LTR even inside RTL text — the bidi algorithm handles this if you don't fight it. Don't force `direction` on number spans; let `Intl.NumberFormat` with the locale render digits (Arabic-Indic vs. Western) and let bidi place them.
+
+## Testing RTL
+
+1. **Pseudo-RTL locale.** Add a fake locale that forces `dir="rtl"` plus pseudolocalized strings to smoke-test layout flip without real translations.
+2. **Snapshot one real RTL locale** (ar) in visual regression.
+3. **Tab order + focus**: verify keyboard navigation follows visual order after the flip.
+4. **Check truncation/ellipsis**: `text-overflow` and gradient fades must sit on the logical end, not a hardcoded right edge.
+5. **Mixed content**: render an LTR username/number inside an RTL sentence and confirm no spillover.