movar-copy
Write or edit user-facing copy in Movar's voice, in both locales, without shipping a claim the code contradicts. Use whenever you touch a user-facing string — the extension UI (packages/i18n), the mar
SKILL.md.claude/skills/movar-copy/SKILL.md
GitHubWrite Movar's copy
docs/copy.md is the authority — nine sections covering
voice, the two sides, UA and EN mechanics, register, lexicon, and the nevers.
Read the sections that bear on your edit before writing. This skill is the
operating procedure around it, not a summary of it.
Where the strings live
| Surface | File |
|---|---|
| Extension UI — popup, options, curtains, errors | packages/i18n/src/messages-{uk,en}.ts |
| Content-script strings | apps/extension/src/lib/i18n/content-strings-{en,uk}.ts |
| Marketing site (all pages, OG, deep dives) | apps/marketing/src/i18n.ts |
| Safari host app | apps/safari-host-app/src/i18n/messages-{uk,en}.ts |
| Store listings, release notes | apps/extension/store-assets/**, RELEASE-NOTES.md |
The four things that actually go wrong
1. One locale ships without the other
UA and EN are both canonical. A new string needs both in the same change —
and they are drafted in parallel, not translated (docs/copy.md preamble).
UA sets the register when one has to land first.
2. The UA reads like a translation
This is the failure mode a machine reaches for by default. docs/copy.md
§4.10–4.14 is the checklist; the tests that catch the most:
- Token-for-token alignment with the EN sibling is the tell. The shipped pair "Got it." — then shows Russian anyway / «Прийнято.» — і показує російською drops anyway in UA because the dash already carries it.
- «дозволяє вам», «допомагає вам», «забезпечує» — direct renderings of allows you to / helps you / provides. Say what happens instead.
- Active participles: «фільтруючий», «блокуючий» → «фільтр», «який блокує».
- Канцелярит: «здійснювати перевірку» → «перевіряти».
- AI register tells: triads, «не просто X, а Y» as a default sentence shape, «У світі, де…», suspiciously even bullet lists.
Mechanics that have no lint rule and are therefore review-only: « » guillemets (§4.2), the ʼ apostrophe at U+02BC (§4.3), em-dash with spaces (§4.4).
3. The copy claims something the product does not do
Every user-facing claim must be literally true against the code, because store reviewers read these surfaces. Verify against the source, not against another copy surface — mirrored copy propagates a wrong claim rather than catching it. Recent examples of claims that were false when written:
- «список сайтів, який ми постійно розширюємо» — there is no list;
@movar/lang-pickerswalks the DOM for any switcher. - Per-element filtering implied to work on marketplaces —
modelsis[googleModel, youtubeModel]and nothing else. - The same claim again, in seven
/uk/guidecallouts: «ховає російські дописи на сторінці — у Facebook, Instagram та X» and six siblings (Telegram, TikTok, Steam, Netflix, Spotify, Gmail). The guide's callouts are now guarded byapps/marketing/src/lib/guide-callouts.test.ts; every other surface still relies on this read. - «Знімки з реальної збірки — не макет» on the homepage drum — the PNGs are
Storybook-rendered approximations with fictitious
.exampledomains, whichapps/extension/store-assets/REQUIREMENTS.mdin fact requires.
Before shipping a capability claim, grep for the behaviour and read it.
4. The claim is true here and stale in six other places
Product claims are mirrored across surfaces with no guard. Changing a
feature or a permission means reconciling every copy of its claim: both
privacy.astro pages, both store PRIVACY-FORMs, STORE-LISTING.md,
docs/copy.md, README.md, the deployment checklist, and the Edge asset notes.
Grep the distinctive phrase across the repo before you consider an edit done.
Procedure
- Read the relevant
docs/copy.mdsections — always §1 (voice) and §7.4 (forbidden lexicon); §4 for UA, §5 for EN, §6 for length caps. - Draft both locales. UA first unless the string is EN-native by nature.
- Verify the claim against code, not against another string.
- Run the §4.10–4.14 pass over the UA — read it aloud; if it maps word for word onto the EN, rewrite it.
- Sweep for mirrors of any claim you changed.
- Check —
pnpm --filter @movar/marketing typecheck, andpnpm check:readmewhen the hero tagline or a product promise moved. Marketing copy changes invalidate the e2e visual baselines; regenerate on a quiet machine (pnpm e2e:baselines:marketing).
When copy.md and the corpus disagree
The corpus wins, and the doc gets corrected in the same change — §4 is explicitly
descriptive of the current corpus. Three rules were found stale this way and
fixed rather than obeyed: a claimed ESLint apostrophe rule that does not exist, a
string path that had moved to packages/i18n, and a ban on «Мовар» that 160
shipped strings ignore. Do not "fix" working copy to satisfy a stale rule.