dualkit/dualkit / plugin/skills/dualkit-convert
dualkit-convert
VerifiedUse when converting an existing English React or Next.js app to Arabic or to English and Arabic with dualkit convert, including filling dualkit-strings.json, placing the language switch, regional suggestions, and fixing what dualkit convert --finish reports
Converting an app
Overview
Phase 1 of dualkit convert rewrites the app's code on a new branch and writes dualkit-strings.json, every English string with its Arabic left to fill. You fill the Arabic. Phase 2, dualkit convert --finish, checks the result and writes a report. Dualkit makes no model calls. Every Arabic string you write is a draft for a native speaker.
1. Ask which mode, then run phase 1
Never pick the mode yourself. Ask the person:
One app that switches between English and Arabic, or a separate Arabic version?
- One app with a switch is
bilingual. English stays exactly as it is. - A separate Arabic version is
arabic. The whole app becomes Arabic and right to left, with no switch.
Then run it with their answer:
npx dualkit convert --mode bilingual
Convert needs a clean git working tree. It makes the branch dualkit/bilingual or dualkit/arabic and never pushes. Other flags:
--start "npm run dev"and--port 3000tell it how to start the app. Ask the person ifdualkit.config.jsonhas no start command. Without one there is no English baseline, and finish cannot run.--no-installskips installing the translation library.--no-baselineskips the English screenshots. Pass it only if the person asks, because the English match then proves nothing.
If convert refuses, it gives a one-line reason. Tell the person and stop.
2. Fill the Arabic in dualkit-strings.json
Each entry looks like this:
{ "key": "checkout.pay", "en": "Pay {amount}", "ar": "", "status": "pending", "file": "app/checkout/page.tsx", "line": 42 }
Fill every entry whose status is pending.
- Edit only
arandstatus. Never changekey,en,fileorline. - Read the code at
fileandlinebefore you translate. A label and an error need different Arabic. - Keep every placeholder and tag, such as
{name}or<b>, exactly as written. Finish refuses a changed one. - Set
statustodraftedonly oncearis filled. Empty entries staypending. Never setreviewed.
Write natural Arabic, not word-for-word English. Follow dualkit-bilingual-copy for register, gender-neutral buttons and plurals. The rules that matter most:
- Modern Standard Arabic for interface text. Gulf dialect only in marketing copy, and only if the person wants it.
- Western digits unless the person asks for Arabic-Indic digits.
- Arabic punctuation:
،؛؟. The full stop stays the same. - Brand and product names stay in Latin script.
3. Run finish and fix what it reports
npx dualkit convert --finish
Stay on dualkit/<mode>, because finish refuses on any other branch. Before each finish run, commit your fixes there with a plain message. Never leave them staged, because finish then refuses.
Finish refuses while any string is still pending. Never pass --force unless the person tells you to ship with English placeholders for the missing Arabic.
It writes dualkit-convert.md and exits 1 when something failed. The report has these sections:
- What changed
- Arabic copy to check
- Regional suggestions
- English pages (bilingual only)
- Arabic pages
- What Dualkit could not convert
- The app's tests
Fix what failed:
- English pages: a fail means the conversion changed how English looks. Open the diff image it names, find the cause in the code and fix it there. Never loosen the check, delete a baseline or skip the English pages to make it pass. If the report says no English baseline was taken, or that no English pages were compared, tell the person English was not proven unchanged.
- Arabic pages: errors come from the dualkit check rules. Fix each one using dualkit-rtl-layout and dualkit-type-pairing.
- What Dualkit could not convert: work through each place it names. Tell the person about pages finish could not reach.
- The app's tests: fix any failure the conversion caused.
Run finish again after each round of fixes. Stop after three runs that still fail. Show the person the report and say what is left.
4. Regional suggestions
The Regional suggestions section covers currency, week start, Hijri dates and browser locale formats. Each is only a proposal. Explain each to the person in one line and apply it only when they say yes to that one. Run finish again after applying any.
5. Place the language switch
Bilingual mode only. Convert writes the switch to components/dualkit-language-switch.tsx, or src/components/ when the app keeps its code in src. It exports DualkitLanguageSwitch. Convert does not place it, because it would change the English look.
Ask the person where it should go, usually the header or main navigation. Add it once finish passes. Any later finish run shows an English difference caused by the switch. Tell the person so.
6. Hand over
At the end, tell the person:
- Every Arabic string is a draft. The Arabic copy to check section lists them all for a native speaker.
- Which drafted strings matter most. Name the ones that carry tone, legal or brand weight, such as headlines, terms, consent text and prices.
- The regional suggestions they turned down, so they can come back to them.
Common mistakes
- Choosing the mode for the person.
- Editing
enorkeyso a string reads better. - Translating
{name}into Arabic. - Passing
--forceto get past pending strings.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |