agentleFS
naomiaronaomiaro/waveform-playlist/.claude/skills/translatable-strings/SKILL.md

translatable-strings

Skill1.7k starsChanged yesterdayMITView on GitHub

Use when adding or changing a React component in packages/ that draws or announces text (a label, a button's text, a tooltip, an aria-label, a placeholder, an option in a select, a formatted readout), when working on issue #808, or when asked whether the library can be translated or works with an i18n framework.

Trending

Quiet this year.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the naomiaro/waveform-playlist repository that our weekly crawl found: only 11 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Who's talking about naomiaro/waveform-playlist

The biggest 5 of 11 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 11

Talked about on GitHub, Stack Overflow and Hacker News (11 times).

On GitHub · 8

3 more on GitHub

On Stack Overflow · 2

On Hacker News · 1

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never build a sentence by joining translated pieces: word order differs between languages.

    line 43
  2. Very specific:

    Before using it, find it: git grep -n 'Messages' -- 'packages/*/src/index.ts*'.

    line 49
  3. Distinctive:

    If it exists: read the default through it, add the new key to the default English table, and keep the prop as the override.

    line 51
  4. Very specific:

    Do not change an English default in passing: e2e specs and consumers' tests find controls by it (getByRole(..., { name, exact: true })).

    line 60
  5. Distinctive:

    Run from the repository root.

    line 68
  6. Very specific:

    Every hit is a finding: a literal written where it is drawn.

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Translatable strings

The library owns no translation framework. Every string a component draws or announces can be supplied by the app; the default is the English text.

Scope: the React packages. The web components in packages/dawcore have no decided mechanism yet (#808).

The order a string is resolved in

  1. The control's own prop, when the app passed one.
  2. The app's entry in the messages catalogue.
  3. The English default.

Both mechanisms exist on purpose (maintainer, 2026-11-13): the catalogue gives an app one place for all strings, the prop overrides a single control.

The prop for each kind of string

StringProp
Visible label or button textchildren
Tooltiptitle
Accessible name with no visible textaria-label
Text built from a value ("120 BPM", "Track 3"), option texts of a select includeda format function prop that takes the value, e.g. formatTempo(tempo), formatRate(rate)

A symbol or a number format is a string too (×, the decimal point in 0.5): it goes through the same format function. State the English default in the prop's JSDoc.

A control in ui-components often has a bound wrapper of the same name in browser or annotations. The wrapper takes the same string props and passes them on; without that the app cannot reach them.

Template: packages/annotations/src/components/DownloadAnnotationsButton.tsx (children and title, English defaults in the destructuring).

Never build a sentence by joining translated pieces: word order differs between languages. One string per message, with the value passed to a format function.

The catalogue

Before using it, find it: git grep -n 'Messages' -- 'packages/*/src/index.ts*'.

  • If it exists: read the default through it, add the new key to the default English table, and keep the prop as the override.
  • If it does not exist yet: give the prop an English default, and post a comment on #808 with one line per string: the file and line, the English text, the prop. Do not invent a catalogue or its name.

Rules that travel with this

  • Ids come from useId(); no literal id= or htmlFor=.
  • Do not change an English default in passing: e2e specs and consumers' tests find controls by it (getByRole(..., { name, exact: true })).
  • A new prop or catalogue key is a doc surface: llm-reference.md, the component's API page, and the package README if it names the component.
  • Development warnings and thrown errors are not translated.

Audit: find strings the app cannot replace

Run from the repository root.

# Literal attribute values
git grep -nE '(aria-label|title|placeholder|alt|label)="[^"]*[A-Za-z][^"]*"' -- \
  'packages/*.tsx' ':!packages/dawcore*' ':!*__tests__*' ':!*.stories.tsx' ':!*.test.tsx'

# Literal JSX text on one line
git grep -nE '>[^<>{}=;()]*[A-Za-z]{2}[^<>{}=;()]*</' -- \
  'packages/*.tsx' ':!packages/dawcore*' ':!*__tests__*' ':!*.stories.tsx' ':!*.test.tsx'

Every hit is a finding: a literal written where it is drawn. A string that is the default of a prop (title = 'Download') matches neither grep.

The greps do not see: JSX text on its own line, an attribute given as an expression (title={'…'}, a ternary), strings held in arrays or objects (select options, menu items, shortcut descriptions), template literals, strings without letters, and .ts files. Read those by hand: selects, menus, dialogs, and any description: or label: field. Example the greps miss: TIME_FORMAT_OPTIONS in packages/ui-components/src/components/TimeFormatSelect.tsx.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.