Kaynos I18n Extract

The t() helper resolves:

1. The current locale's translation
2. If missing, falls back to the English string (NOT the key itself — KAY-655 fix)
3. If still missing, returns the key string

Pattern B: <FormattedMessage> component

Best for longer strings with embedded HTML / pluralization.

import { FormattedMessage } from "react-intl";

<h2>
  <FormattedMessage
    id="admin.section.title"
    defaultMessage="Academy Settings"
  />
</h2>

defaultMessage is required — it's the English fallback and is what the UI shows if the key doesn't exist in the loaded locale.

When to use which

• Labels, button text, aria-labels → Pattern A (t())
• Paragraphs, headings with embedded formatting, plurals → Pattern B (FormattedMessage)
• Toast messages, dynamic user-facing errors → Pattern A (t() with values object)

Extracting a hardcoded string

Step 1: Identify hardcoded English

// Before
<button aria-label="Mark all as read">Mark all read</button>
<p>No sessions yet. Upload your first video to get started.</p>

Step 2: Pick semantic keys

Naming convention: <area>.<subarea>.<purpose>. Match existing keys in en.json before inventing new ones.

notifications.markAllRead.button
notifications.markAllRead.ariaLabel
sessions.empty.title
sessions.empty.hint

Step 3: Add keys to both locales

src/i18n/en.json:

{
  "notifications.markAllRead.button": "Mark all read",
  "notifications.markAllRead.ariaLabel": "Mark all as read",
  "sessions.empty.title": "No sessions yet",
  "sessions.empty.hint": "Upload your first video to get started."
}

src/i18n/es.json:

{
  "notifications.markAllRead.button": "Marcar todo como leído",
  "notifications.markAllRead.ariaLabel": "Marcar todo como leído",
  "sessions.empty.title": "Aún no hay sesiones",
  "sessions.empty.hint": "Sube tu primer video para comenzar."
}

If you don't speak Spanish, prefix the value with [EN] so a translator can find them later:

{
  "sessions.empty.title": "[EN] No sessions yet",
  "sessions.empty.hint": "[EN] Upload your first video to get started."
}

Parity is non-negotiable — both files must have identical keys, even if values are flagged English.

Step 4: Replace the hardcoded strings

// After
import { useTranslation } from "../hooks/useTranslation";

export default function NotificationsHeader() {
  const { t } = useTranslation();
  return (
    <button aria-label={t("notifications.markAllRead.ariaLabel")}>
      {t("notifications.markAllRead.button")}
    </button>
  );
}

Step 5: Handle interpolation

Values with dynamic parts use react-intl's ICU syntax:

{
  "sessions.progress": "{count} of {total} watched",
  "sessions.countLabel": "{count, plural, one {# session} other {# sessions}}"
}

<span>{t("sessions.progress", { count: 3, total: 10 })}</span>
// OR for plural
<FormattedMessage
  id="sessions.countLabel"
  values={{ count: sessions.length }}
/>

Areas still known to have hardcoded strings (opportunities)

• src/components/DrawingCanvas.jsx — tool labels
• src/components/ClipEditor.jsx — form labels
• Various admin sub-sections

Check with:

# Find likely English strings inside JSX (imperfect but useful)
grep -En '>[A-Z][a-z]+[^<]{3,30}<' src/components/MyComponent.jsx

Parity check

Before committing:

node -e "
const en = require('./src/i18n/en.json');
const es = require('./src/i18n/es.json');
const enKeys = new Set(Object.keys(en));
const esKeys = new Set(Object.keys(es));
const inEnOnly = [...enKeys].filter(k => !esKeys.has(k));
const inEsOnly = [...esKeys].filter(k => !enKeys.has(k));
console.log('Missing in ES:', inEnOnly.length ? inEnOnly : 'none');
console.log('Missing in EN:', inEsOnly.length ? inEsOnly : 'none');
"

If keys are missing on either side, add them before commit. Every key in one MUST exist in the other.

What NOT to i18n

• Keys/IDs/slugs ("admin", "student", "session_type")
• Test-only strings (mock data, test titles)
• Developer log messages (console.error("DB query failed")) — those stay English
• Error codes sent over the wire — map at the UI boundary using formatUserFacingError

Handling dynamic strings

Never concatenate translated pieces — it breaks locales with different word order. Always use a single key with placeholders:

// BAD
{t("prefix") + " " + user.name + " " + t("suffix")}

// GOOD
{t("greeting.withName", { name: user.name })}
// en: "Welcome, {name}!"
// es: "¡Bienvenido, {name}!"

Aria labels and placeholders

These count as user-visible strings and MUST be translated:

<input
  type="search"
  placeholder={t("search.placeholder")}
  aria-label={t("search.ariaLabel")}
/>

Verify before commit

1. npm run build — no runtime errors from missing keys
2. npm test — no tests broken by key renames
3. Spot-check the component rendered (both locales if possible)
4. Parity check as above

See also: kaynos-add-component-test, kaynos-decompose-file.