BloomDesktop: Skill for Claude Code

Apply this skill whenever you add a new localizable string to the codebase, modify an existing one, or review XLF files as part of a task.

This skill is the how — the procedure for each operation. The why — how Crowdin actually works and what each kind of edit does to existing translations — lives in one place, DistFiles/localization/README.md. Where a rule here has a reason, that reason is written there and cited from here rather than restated, so the two can't drift into telling you different things. Read its "Why we can't just delete a string" section before you conclude that any deletion or id change is harmless.

Files

Localizable strings live in DistFiles/localization/en/. Only ever add or change strings in the English subdirectory — never touch the other language folders.

There are three priority files. Choose based on what the string labels:

File	Use for
Bloom.xlf	The most important things in our UI that users must understand
BloomMediumPriority.xlf	Secondary options, help text, feature-specific instructions, important error messages
BloomLowPriority.xlf	Rarely-seen text like error messages

Strings that are only meant to be seen by developers or if code bugs occur should not be localized. Add comments explaining why they are not.

Making a string in React code localizable

The front end localizes strings in two ways:

• an l10n-aware component, e.g. <BloomButton l10nKey="myKey">My Text</BloomButton> or <H1 l10nKey="myKey">My Text</H1>;
• the hook useL10n("My Text", "myKey") — the English text first, then the id. It lives in src/BloomBrowserUI/react_components/l10nHooks.ts; import it by the correct relative path.

import { useL10n } from "../../react_components/l10nHooks";
// somewhere in the Foobar dialog
<button>{useL10n("Brighten everything", "FoobarDialog.BrightenEverything")}</button>

Do not fill in the l10nComment parameter of useL10n; it clutters the code, and the translator's context goes in the XLF <note> instead (below).