Style Guide Creation

Help the user produce a Crowdin style guide by analyzing paired source-and-translation material and turning the recurring linguistic decisions into a reusable set of rules. Output is two artifacts that ship together: a human-readable Markdown guide (uploaded as the guide's content) and a compact aiInstructions summary (what AI Pipeline / pre-translation actually reads).

A style guide is the layer above a glossary. The glossary locks individual terms; the style guide locks the patterns — tone of address, punctuation conventions, number and date formatting, button-label form, capitalization, brand voice. Without one, translators (human or AI) make these calls independently every time, and inconsistencies pile up across files. With one grounded in the team's real translations, the rules already match what's been shipped, so adopting it doesn't trigger a rewrite of existing work.

This workflow stays human-in-the-loop and evidence-driven: every rule that lands in the guide must be backed by at least two real occurrences from the user's paired material. A 12-rule guide built from observed patterns is more useful than a 60-rule template the team has to argue with.

Workflow

1. Take stock. Call list_style_guides. If a project is in scope (named in the user-prompt context or by the user), look at which guides are already attached (projectIds includes the project id) and which target languages each covers (languageIds). If no project is in scope, list the org-wide guides plainly.

   Give the user a one- or two-sentence summary of what already exists — names, target languages, attachment status. Don't dump the raw list; the user mostly cares whether something is already there for the language they're about to ask for.

2. Set up the run — four upfront answers. Get all four before any analysis. Bouncing back to the user partway through analysis to ask "wait, which language?" wastes a round-trip and feels sloppy.

   (a) Target language(s). Ask via AskUserQuestion if the message doesn't already name one. Style-guide rules are heavily language-specific — ти/ви, «»/„", 1 000,00 vs 1,000.00, formal vs informal address — so this drives almost everything else.

   (b) One guide per language, or one unified guide? Ask via AskUserQuestion. Default to per-language and recommend it: the rules don't overlap much across languages, and a per-language guide is shorter, easier to maintain, and easier to assign via languageIds. The unified option is for teams that want a single document with sections per language (often for internal review). Whichever they pick, the content is still structured per-language under the hood — "unified" just means one Crowdin StyleGuide entity covering several languageIds.

   (c) Create new, or extend existing? Only relevant if step 1 surfaced a guide matching the target language(s). Offer both via AskUserQuestion:

   • Extend the existing guide. Fetch its current content (get_style_guide → downloadLink, then WebFetch the URL to read the markdown). Use this as the baseline; your job becomes additions and corrections rather than starting from scratch. Don't propose rules that contradict the existing guide silently — if the analysis finds the team has actually been doing the opposite of a stated rule, flag the conflict and let the user decide which is canonical.
   • Create a new guide. Ask for the name (e.g. "UA Style Guide", "Brand Voice — DE"). If a project is in scope, plan to set projectIds: [<id>] on creation so it's attached automatically.

   (d) What paired source-and-translation material should I analyze? Ask in plain text — paired material is the non-negotiable input for this skill. Acceptable forms, in rough order of preference:

   • Bilingual files attached to this chat. CSV/XLSX with paired columns (source / translation), TMX, XLIFF, PO/POT — each row already aligned. Highest-quality input.
   • A Crowdin project with existing translations (when a project is in scope). Use list_strings + list_language_translations for the chosen target language; pair each string with its top-voted or approved translation.
   • A source URL and its translated mirror. Marketing site + its /uk, /de, /es locale. Fetch both with WebFetch, align by structural position (headings, paragraphs usually map 1:1 between mirrors).
   • Separate source + translation files attached to this chat. Two files the user expects you to align — useful when the structure is parallel (chapter 1 ↔ chapter 1).

   Require paired material — don't proceed without it. This skill exists to extract rules from real translation decisions; without translations, there's nothing to extract. If the user offers only source content (no translations), stop and ask for paired material: "I need to see how this content has actually been translated — can you share a bilingual file, the project's existing translations, or a translated version of the URL?" Don't fall back to generic best practices for the language — that's a template, not a style guide, and the user will discover the mismatch the first time they read it. The one acceptable accommodation is "extend existing guide" mode (step 2c) where some of the rules can be inherited from the baseline without re-deriving them, but additions still need evidence.

   When the user is genuinely pre-launch — offer a pre-translation brief instead. If the user replies that they truly have no paired material because translation hasn't started yet, don't just leave them empty-handed. Offer to produce a different artifact: a short pre-translation brief covering the foundational decisions translators need before day one — address form (e.g. du/Sie, ти/ви), quote-mark style, decimal/thousands separator, date format, currency placement, and how the product's brand and feature names should be handled (translate vs keep English vs mixed). Make it explicit this is not a style guide — it's a one-pager that unblocks translators and produces material that becomes a style guide once the first batch comes back. The user gets value now and the workflow has a clean entry point next time.

3. Sample, don't exhaust. A few hundred paired entries is enough to surface dominant patterns; reading 10,000 is wasteful and dilutes the signal with noise. Pick samples that span variety:

   • For Crowdin project strings: prefer the most-translated files (highest activity) and approved translations over drafts. Approved translations carry more signal than the latest unreviewed guess.
   • For bilingual files: read all of them if under ~500 rows; otherwise sample evenly (every Nth row), not just the first chunk — the start of a file is often boilerplate or headers.
   • For URL pairs: the rendered text bodies are usually enough; skip nav/footer chrome.

   If a category (e.g. date formatting) only has one or two examples in the sample, that's not a rule yet — note it as "low confidence, only 1 example found" and let the user decide whether to include it or expand the sample.

4. Analyze across the standard categories. Look at the paired material and ask: what decision was made repeatedly, and was it made consistently? Eight categories cover almost everything that belongs in a translation style guide:

   Category	What to look for
   Tone & address	Formal vs informal pronoun (ти/ви, du/Sie, tu/vous, tú/usted); imperative vs nominal phrasing in instructions; reading register (friendly vs corporate vs technical)
   Grammar & syntax	Sentence length, voice (active vs passive), use of present vs past for instructions, contractions, sentence-initial connectives
   Punctuation	Quotation-mark style (« » vs „ " vs " "); em-dash / en-dash / hyphen usage; spaces before punctuation (FR : ;, narrow no-break spaces); Oxford comma; ellipsis as … vs ...
   Capitalization	Title case vs sentence case for headings and buttons; brand-name casing (crowdin vs Crowdin); capitalization of UI-element names mid-sentence; DE noun capitalization edge cases
   Numbers, dates, times	Thousands and decimal separators (1,000.00 vs 1 000,00 vs 1.000,00); date order (DD.MM.YYYY vs MM/DD/YYYY); 12h vs 24h time; currency placement; unit spacing
   UI & interaction text	Button-label form (verb-led "Save changes" vs nominal "Settings"); error-message tone; confirmation phrasing; tooltip length; placeholder style
   Inclusive & gender-sensitive language	Gender-neutral phrasing, generic you vs gendered alternatives, locale-specific inclusive forms (DE innen / :, ES @ / e), accessibility wording
   Non-translatable / preservation rules	Brand names; product / SKU names; code identifiers (API_KEY); placeholder syntax ({count}, %s, {{name}}); HTML / Markdown markup; URL handling

   For each category, hold yourself to at least two paired examples showing the same decision before you write a rule. One example is an anecdote; two is a pattern; three or more is canon. One example is not enough, even when the rule "feels obvious for the locale". If the only evidence for "24-hour time" is a single 8:42 PM → 20:42 conversion, that's an anecdote — drop the rule and note the gap, don't sneak it in because it's the locale default. The user can add it back in their reply if they want it locked. The reason: a style guide grounded in one observation is just a template wearing a costume; you trade the credibility of "this is what your team does" for "this is what I assumed your team does", and the user catches it the moment they spot the rule with no real example behind it.

   If the team is inconsistent (half ти / half ви), don't pick one silently — flag the disagreement in the draft and ask the user which is canonical (see step 5).

   When the team's pattern conflicts with the language's standard convention — flag, don't codify. Sometimes the paired material shows the team has consistently done something that contradicts a well-known norm for the target language. Examples:

   • Capitalizing common nouns mid-sentence in Ukrainian / Russian / French (the team mirrors EN capitalization; the locale convention is lowercase).
   • Using straight "..." quotes when the locale convention is «...» / „..." / « ... ».
   • Placing the currency symbol before the amount in a locale where it conventionally goes after.

   In these cases, don't automatically codify the team's pattern just because evidence count is ≥2. The team may have drifted into a non-standard practice through one translator's habit and never noticed. Instead, surface the pattern AND the locale norm side by side and ask the user which is canonical:

   "Found 9 examples with capitalized product nouns ('Рахунок', 'Транзакція', 'Бюджет') mirroring the English source. Standard UA convention is lowercase common nouns mid-sentence. Lock in the team's pattern or normalize to the UA norm?"

   This protects the user from compounding a translation-quality issue into a written rule that future translators will then follow as gospel. If the user confirms the drift is intentional (sometimes brand voice deliberately mirrors EN), codify it; otherwise treat it as an inconsistency to fix in the translations, not a rule.

   Don't fish for rules in every category. Some projects genuinely don't have a stance on, say, inclusive language because their content is UI-only buttons; forcing a rule there produces noise. If the material doesn't contain enough signal for a category, leave it out.

5. Draft the guide and present it inline for review. Output two parts in one message, both visible in the chat — don't upload first and ask "looks good?" after, because the user can't edit a file in storage.

   Part A — the Markdown style guide. Group by the categories from step 4 (skip empty ones). Each rule:

   • One sentence stating the rule.
   • One Do example and one Don't example, lifted verbatim from the user's paired material (source + translation, side by side).
   • A short rationale only when the rule would surprise a reader — most rules don't need one.

   Use this skeleton (omit sections that have no rules):

   # <Language> Style Guide — <Brand / Project>
   
   ## Tone & address
   - Use the informal *ти* form for all user-facing copy.
     - ✅ "Зайди в налаштування і вибери мову."
     - ❌ "Зайдіть в налаштування і виберіть мову."
   - Prefer imperative instructions over nominal phrasings.
     - ✅ "Натисни «Зберегти»."
     - ❌ "Збереження виконується натисканням «Зберегти»."
   
   ## Punctuation
   - Use «guillemets» for quotation marks; do not use straight " " or English " ".
   - …

   Keep the first draft tight — roughly 8–15 rules total, not 40. The user will add what's missing; over-padding makes the review painful.

   Part B — the aiInstructions summary. A compact 6–10 line plain-text version aimed at AI Pipeline / pre-translation, not human translators. Reads as direct instructions in present tense:

   Translate from English to Ukrainian using informal *ти* address.
   Use «guillemets» for quotation marks, never " " or " ".
   Format numbers as 1 234,56 (space thousands separator, comma decimal).
   Use DD.MM.YYYY for dates.
   Keep placeholders ({0}, %s, {{name}}) and HTML tags exactly as in source.
   …

   This is what AI translators see in their system prompt during pre-translation. It must be short, declarative, and unambiguous — no "consider" / "where appropriate" / "generally" hedges. If a rule has open cases the team hasn't decided, leave it out of aiInstructions (it can still live in the Markdown for humans).

   Ask for changes in writing. End the draft with one explicit line: "Reply with any rules you want removed, edited, or added — and the rest I'll apply as-is." The user is in a chat; they can't click. Spell out that they reply with text.

   Flag inconsistencies, don't paper over them. If the paired material shows the team has actually done a thing two different ways, name both and ask which is canonical instead of picking one. Example: "Found 14 examples using «», 9 examples using „" — which is canonical?" This is the single most valuable thing the workflow does, because the user often doesn't realize their content has drifted until they see the count.

   Foundational choices block the draft — resolve them before, not inside the Markdown. Some choices are foundational: they color every other example in the guide. The big ones are address form (formal vs informal — ти/ви, du/Sie, tu/vous), currency-placement style, quote-mark family, and whether UI element names are translated or kept in English. When one of these is contested in the paired material, don't write a draft with a [TBD] placeholder while the rest of the rules' examples already use one side of the unresolved choice — those examples silently lock in a decision the user hasn't made. Two acceptable patterns:

   1. Answer-first (preferred): present the foundational disagreement(s) at the top of the message, ask the user to pick via AskUserQuestion or a short text question, and defer the rest of the draft to the next round. Cleaner output, no inconsistency-in-disguise.
   2. Neutral-example drafting (only if you really want to ship a single message): write every example without committing to the contested choice — use noun forms, infinitives, or impersonal constructions that work under either answer. This is harder; if you can't naturally write neutral examples for a rule, that's a signal to fall back to (1).

   Lower-stakes inconsistencies — a single capitalization outlier, mixed em-dash spacing — can be flagged inside the draft using ❌/✅ pairs without holding back the whole guide. Foundational ones cannot.

6. Apply once approved. Three calls in sequence:

   1. Upload the Markdown content via add_storage. The filename should end in .md (e.g. ua-style-guide.md); Crowdin uses the extension to render the content correctly in the UI. Capture the returned id — that's the storageId.
   2. Create the guide via create_style_guide({ name, storageId, aiInstructions, languageIds: [<lang>], projectIds: [<project>] }). Pass projectIds only if a project is in scope. Pass languageIds always — even in unified mode (list every target language the guide covers).
   3. Extend mode instead: if step 2c chose "extend existing", skip create_style_guide. Use edit_style_guide(id, [{ op: "replace", path: "/storageId", value: <newStorageId> }, { op: "replace", path: "/aiInstructions", value: <newAiInstructions> }]). The edit endpoint follows JSON Patch — each change is a { op, path, value } operation, paths are JSON-pointer (/aiInstructions, /name, /languageIds, /projectIds, /storageId). Don't delete_style_guide and recreate — that breaks the webUrl link the user may have already shared with translators.

   Report what landed in one line: guide name, target language(s), project attachment (if any), and the webUrl from the response so the user can open it. Example: "Created 'UA Style Guide' for Ukrainian, attached to project Aurora — open at ."

7. Offer a follow-up only when relevant. After applying, don't auto-propose another round. Reasonable follow-ups to offer:

   • "Want me to draft one for another target language?" (only if the user mentioned multiple languages or the project has more target languages).
   • "Want me to expand a category we kept short — e.g. UI text — by sampling more material?" (only if you actually skipped or thinned a category in step 4 due to sparse evidence).
   • Otherwise stop.

Quality Bar

• Evidence-based, not template-based. Every rule must be backed by ≥2 paired examples from the user's material. A single observation — even a clear locale-default one like "24h time" from one date conversion — is an anecdote, not a rule; drop it. The cost of an unfounded rule is high: future translators follow it as gospel, and the user can't tell which rules came from their team's actual practice and which the agent guessed. If you find yourself writing a rule because "it's the standard for Ukrainian" without observing it in the user's translations, leave it out.
• Flag the team's drift instead of codifying it. When the team's translations conflict with a well-known locale convention (UA capitalization, FR punctuation spacing, ES currency placement, etc.), don't auto-codify the drift just because evidence count is ≥2. Surface the conflict and let the user decide (see step 4).
• Foundational choices come before examples. If address form, currency style, or quote family is contested, resolve it before writing rule examples — don't ship a draft where the address form is [TBD] but every example already commits to one side (see step 5).
• Short over comprehensive. 8–15 rules in the first draft is the target. A 40-rule guide nobody reads is worse than a 12-rule guide the team actually adopts.
• Examples must be real. Pull the Do and Don't examples from the paired material, not invented. If the team's translation uses straight " instead of «», that's the ❌ example — not something you made up.
• Don't restate the glossary. Individual term decisions ("Cart → Кошик") belong in the glossary, not the style guide. Style guide rules are patterns ("use guillemets"), not entries ("the word X translates to Y"). When a rule starts feeling like a terminology entry, drop it and suggest the user add it to a glossary instead.

Edge Cases

• No paired translations available, user is pre-launch. Stop and ask for paired material — but if the user confirms they truly haven't started translating yet, offer a pre-translation brief as an alternative artifact (foundational decisions translators need on day one: address form, quote style, decimal format, date format, currency placement, brand-name handling). Frame it explicitly as not-a-style-guide; the goal is to unblock the first translation pass so a real style guide can be derived from it later. See step 2(d).
• Team's translations conflict with the language's standard convention. Don't quietly codify the drift. Surface "team uses X, locale norm is Y" and ask which is canonical — the team often hasn't noticed, and locking in their drift in a written rule makes it self-reinforcing across all future translators. See step 4.
• Foundational choice is contested (address form, currency style, quote family). Resolve via answer-first round rather than shipping a draft with [TBD] placeholders next to examples that already pick a side. See step 5.
• Paired material is tiny (under ~20 entries). Tell the user up front: "I can draft a starter guide but with this little material, several categories will be 'low confidence'. Want me to proceed, or wait until more translations are in?" Don't silently produce a thin guide and present it as authoritative.
• Translations disagree on a pattern. Surface the counts ("14 uses « », 9 use „ "") and ask which is canonical. Never pick silently — the user often doesn't know about the drift until they see the numbers.
• Existing guide contradicts the analysis. In extend mode, if the existing guide says one thing and the team's actual translations show the opposite, flag the conflict explicitly: "Existing guide says X; observed translations show Y — which should win?" Don't quietly overwrite the existing rule.
• User asks for several target languages in one go. Honor it, but draft them sequentially — present language 1 for review, apply, then move to language 2. Trying to draft 4 languages in one message produces an unreviewable wall and makes inconsistency-flagging muddy across languages.
• User attaches a TMX or XLIFF. Parse it directly — the source and target are already aligned by <tu> / <trans-unit>. No need to ask for matching files.
• CSV/XLSX columns are unlabeled. Look for cues: language identifiers in headers (en, uk, source, translation), or the obvious shape (left column ASCII Latin, right column Cyrillic). If genuinely ambiguous, ask once which column is the source.
• URLs fail to fetch or the translated mirror is missing pages. Tell the user which URL failed and why; continue with the rest. Don't silently drop a source they handed you.
• Project has approved + unapproved translations. Prefer approved. If a string has both, use the approved version; ignore drafts. Drafts haven't been QA'd and including them dilutes the signal.
• User asks for the AI Instructions only, no Markdown guide. Honor it — produce just aiInstructions and use create_style_guide with storageId: null (or skip the storage upload). Tell the user the human-facing guide is empty.
• User edits the draft heavily in the review reply. Treat their edits as the source of truth. Don't push back on individual changes ("but the data says X") — they own the rules; the analysis is input, not judgment.
• Asked to delete / rename / re-share an existing guide. Out of scope for this skill. Use edit_style_guide or delete_style_guide directly from a regular agent turn; don't load this skill for routine maintenance.

Reporting

After applying, one short line: name, target language(s), project attachment if any, and the webUrl. No long summaries — the user can open the guide in Crowdin and see it.

When stopping mid-flow (user said stop, or paired material was insufficient), say so plainly and tell the user what would unblock continuing (e.g. "share a bilingual export from project X and we can pick up here").

Tool Reference

All Crowdin MCP tools are namespaced as mcp__crowdin__<tool> (e.g. mcp__crowdin__create_style_guide). WebFetch and AskUserQuestion are Claude Agent SDK built-ins, not Crowdin MCP tools.