What is project-locale?

This Claude skill provides a comprehensive guide for implementing Flutter localization (l10n) within the app_lib/locale package. It streamlines the process of adding user-facing text, managing ARB files, and maintaining naming conventions to ensure a consistent and scalable internationalization workflow. By following this guide, developers can efficiently handle multi-language support while adhering to project-specific best practices and automation scripts.

When should I use project-locale?

project-locale is useful in the following scenarios: • Adding new user-facing strings to Flutter widgets using the context.l10n extension for seamless internationalization. • Creating and configuring support for new locales (e.g., translating English ARB templates to Chinese or other languages). • Standardizing ARB key naming conventions (e.g., btnAction, navItem) to maintain a clean and searchable localization codebase. • Troubleshooting common localization errors and automating code generation using Melos or Flutter gen-l10n commands. • Implementing parameterized strings and pluralization rules within ARB files to handle complex UI text requirements.

name	project-locale
description	Guide for adding localized text using l10n in app_lib/locale package (project)

Flutter Localization Skill

This skill guides adding localized text following this project's l10n conventions.

When to Use

Trigger this skill when:

Adding new user-facing text to the app
Creating new screens or widgets with text content
User asks to "add text", "localize", "translate", or "add string"

Package Location

All localization files are in app_lib/locale/:

app_lib/locale/
├── l10n.yaml              # Flutter gen-l10n configuration
├── lib/
│   ├── app_locale.dart    # Main export with delegates
│   ├── arb/
│   │   └── app_en.arb     # Template ARB file (English)
│   ├── extensions/
│   │   └── build_context.dart  # context.l10n extension
│   └── gen_l10n/          # Generated files (do not edit)
└── pubspec.yaml

Adding New Text

Step 1: Add to ARB File

Edit app_lib/locale/lib/arb/app_en.arb:

{
  "@@locale": "en",
  "existingKey": "Existing text",
  "newKey": "Your new text here",
  "newKeyWithParam": "Hello {name}!",
  "@newKeyWithParam": {
    "placeholders": {
      "name": {
        "type": "String",
        "example": "John"
      }
    }
  }
}

Step 2: Regenerate Localizations

melos run gen-l10n

Or from the locale package:

cd app_lib/locale && flutter gen-l10n

Step 3: Use in Widgets

import 'package:app_locale/app_locale.dart';

// In a widget's build method:
Text(context.l10n.newKey)
Text(context.l10n.newKeyWithParam(userName))

ARB Key Naming Conventions

Pattern	Example	Use Case
`camelCase`	`welcomeMessage`	Simple text
`screenAction`	`homeTitle`, `settingsBack`	Screen-specific text
`navItem`	`navHome`, `navSettings`	Navigation items
`btnAction`	`btnSubmit`, `btnCancel`	Button labels
`errorType`	`errorNetwork`, `errorAuth`	Error messages
`msgType`	`msgSuccess`, `msgLoading`	Status messages

Parameterized Strings

Basic Parameter

{
  "greeting": "Hello {name}!",
  "@greeting": {
    "placeholders": {
      "name": {"type": "String"}
    }
  }
}

Usage: context.l10n.greeting('Alice')

Multiple Parameters

{
  "itemCount": "{count} items in {category}",
  "@itemCount": {
    "placeholders": {
      "count": {"type": "int"},
      "category": {"type": "String"}
    }
  }
}

Usage: context.l10n.itemCount(5, 'Books')

Pluralization

{
  "itemsSelected": "{count, plural, =0{No items} =1{1 item} other{{count} items}} selected",
  "@itemsSelected": {
    "placeholders": {
      "count": {"type": "int"}
    }
  }
}

Adding New Locales

Step 1: Create New ARB File

Copy app_en.arb to app_<locale>.arb (e.g., app_zh.arb):

cp app_lib/locale/lib/arb/app_en.arb app_lib/locale/lib/arb/app_zh.arb

Step 2: Update Locale Tag

Change "@@locale": "en" to "@@locale": "zh" and translate all values.

Step 3: Register Locale

Edit app_lib/locale/lib/app_locale.dart:

static List<Locale> supportedLocales = [
  const Locale('en'), // English
  const Locale('zh'), // Chinese
];

Step 4: Regenerate

melos run gen-l10n

Best Practices

Always use l10n - Never hardcode user-facing strings
Descriptive keys - Use meaningful camelCase key names
Group related strings - Use prefixes (nav*, btn*, error*, etc.)
Document placeholders - Always include @key metadata for parameterized strings
Run gen-l10n - Always regenerate after ARB changes
Test with context - Ensure widgets have BuildContext access for l10n

Quick Reference

// Import
import 'package:app_locale/app_locale.dart';

// Simple text
context.l10n.appName

// With parameter
context.l10n.greeting(userName)

// In non-widget context (pass context)
AppLocalizations.of(context).appName

Common Errors

Error	Cause	Fix
`l10n not found`	Missing import	Add `import 'package:app_locale/app_locale.dart';`
`key undefined`	Not regenerated	Run `melos run gen-l10n`
`null check`	No localization delegate	Ensure `AppLocale.localizationsDelegates` in MaterialApp

project-locale

When & Why to Use This Skill

Use Cases