agentleFS
WaniWani-AIWaniWani-AI/sdk/.claude/skills/translations/SKILL.md

translations

Skill18 starsChanged 9 days agoMITView on GitHub

Add or update translations for pages and components in the Waniwani app. Use when the user wants to add translations, create translation files, internationalize a page, make text translatable, or update existing translations. Also use proactively when creating new pages or components with user-facing text.

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 8 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Only use a different location if the user explicitly requests it.

    line 34
  2. Distinctive:

    Static text (never changes): Use plain strings

    line 80
  3. Distinctive:

    Dynamic text (includes variables): Use functions with object parameters

    line 85
  4. Distinctive:

    When creating or updating translations:

    line 116
  5. Distinctive:

    All 2 languages have identical structure

    line 161
  6. Distinctive:

    No missing keys in any language

    line 162
  7. Distinctive:

    No extra keys in any language

    line 163
  8. Distinctive:

    Use descriptive, camelCase names that match the feature:

    line 170

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “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

Waniwani Translation System

Automatically create and manage translations for pages and components using the Waniwani translation system.

📚 For real-world examples, see examples.md in this directory.

When to Use This Skill

Apply this skill when:

  • Creating new pages or components with user-facing text
  • Adding translations to existing pages
  • Updating translation files
  • Internationalizing hardcoded text
  • The user mentions "translations", "translate", "i18n", "internationalization", or language support

Translation File Location

CRITICAL: Co-locate @translations.ts with page.tsx by default

src/app/(app)/settings/teams/
├── page.tsx              # The page component
├── @translations.ts      # Translations file (place HERE)
└── loading.tsx

Only use a different location if the user explicitly requests it.

Mandatory Requirements

🚨 ALL pages and components MUST support all 2 languages:

  • English (en)
  • French (fr)

No exceptions. TypeScript will enforce structural equality across all languages.

Translation File Structure

import { defineTranslations } from "@/lib/translations/types";

export const descriptiveName = defineTranslations({
  en: {
    // Static text - plain strings
    title: "Page Title",

    // Dynamic text - functions with object parameters
    greeting: ({ name }: { name: string }) => `Hello ${name}!`,

    // Nested structure for organization
    actions: {
      save: "Save",
      cancel: "Cancel",
    },
  },
  fr: {
    // Must match "en" structure exactly
    title: "Titre de la page",
    greeting: ({ name }: { name: string }) => `Bonjour ${name} !`,
    actions: {
      save: "Enregistrer",
      cancel: "Annuler",
    },
  },
});

See examples.md for comprehensive real-world examples.

Static vs Dynamic Content

Static text (never changes): Use plain strings

title: "Settings"

Dynamic text (includes variables): Use functions with object parameters

greeting: ({ name }: { name: string }) => `Hello ${name}!`

❌ Never use:

  • Template placeholders: "Hello {name}!"
  • Direct parameters: (name) => ...

Using Translations in Components

"use client";
import { useTranslation } from "@/lib/translations/hooks";

export function MyComponent() {
  const t = useTranslation("descriptiveName");

  return (
    <div>
      <h1>{t.title}</h1>  {/* Static */}
      <p>{t.greeting({ name: "World" })}</p>  {/* Dynamic */}
    </div>
  );
}

See examples.md for complete component examples with forms, tables, and validation.

Required Workflow

When creating or updating translations:

  1. Create @translations.ts next to page.tsx with all 2 languages (en, fr)
  2. 🚨 CRITICAL: Run rebuild script immediately after creating/modifying translations:
    bun translations:build
    This regenerates the translation index and makes translations available. YOU MUST RUN THIS after any translation file changes!
  3. Import and use useTranslation() in components
  4. Verify by checking TypeScript errors (missing keys will error immediately)

Translation Coverage Checklist

Translate ALL user-facing text:

  • ✅ Page titles and descriptions
  • ✅ Button labels and action text
  • ✅ Form labels and placeholders
  • ✅ Error messages and validation text
  • ✅ Table headers and column names
  • ✅ Dialog/modal titles and content
  • ✅ Toast notification messages
  • ✅ Empty state messages
  • ✅ Loading and status text
  • ✅ Help text and tooltips
  • ✅ Navigation items

Common Mistakes to Avoid

❌ Hardcoded strings: <h1>Settings</h1> ✅ Use translations: <h1>{t.title}</h1>

❌ Template placeholders: greeting: "Hello {name}!" ✅ Use functions: greeting: ({ name }) => ...

❌ Missing languages: Only defining en without fr ✅ All languages: TypeScript enforces both en and fr

❌ Forgetting rebuild: Creating files without running bun translations:build ✅ Always rebuild: Run bun translations:build after changes

Type Safety Benefits

TypeScript enforces:

  • All 2 languages have identical structure
  • No missing keys in any language
  • No extra keys in any language
  • Correct parameter types for dynamic functions

If structures don't match, you'll get immediate TypeScript errors before runtime.

Export Naming Convention

Use descriptive, camelCase names that match the feature:

  • ✅ settings - for settings page
  • ✅ userProfile - for user profile
  • ✅ dashboardHome - for dashboard home
  • ✅ teamMembers - for team members page

Additional Resources

  • 📚 Examples: See examples.md in this skill directory for comprehensive real-world examples
  • Translation types: src/lib/translations/types.ts
  • Translation hooks: src/lib/translations/hooks.ts
  • Locale context: src/lib/translations/locale-context.tsx
  • Auto-generated index: src/lib/translations/index.ts (DO NOT EDIT)
  • Example files: Search for existing @translations.ts files in the codebase

Proactive Application

Apply this skill automatically when:

  • Creating new pages or components
  • Modifying existing pages to add new text
  • User asks to "add a page" or "create a component"
  • Any task involving user-facing text

Don't wait for the user to explicitly request translations—apply them proactively!

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.