intl

The intl package uses a single global locale called defaultLocale. Most operations use this locale unless explicitly overridden. You can manage locales in three ways:

1. Set the global locale: Use Intl.defaultLocale to change the locale for the entire application.
2. Override for a specific operation: Use Intl.withLocale(locale, () => ...) to run a specific block of code with a different locale. This is preferred if your application uses multiple locales simultaneously, as it also covers async tasks spawned within that block.
3. Specify locale per object/method: Create format objects (like DateFormat) with a specific locale, or pass a locale parameter directly to methods.

// Set global locale
Intl.defaultLocale = 'pt_BR';

// Override for a specific operation
Intl.withLocale('fr', () => print(myLocalizedMessage()));

// Specify locale in a format object
var format = DateFormat.yMd('ar');
var dateString = format.format(DateTime.now());

// Specify locale in a method call
print(myMessage(dateString, locale: 'ar'));

The Intl class is the primary entry point for internationalization tasks in Dart. It provides methods for message formatting (including plurals, gender, and selection), date/number formatting, and locale management.

Key capabilities:

• Message Formatting: Use Intl.message, Intl.plural, Intl.gender, and Intl.select to create translatable strings.
• Locale Management: Set a defaultLocale or use Intl.withLocale to run specific code blocks with a different locale.
• Formatting: Create locale-aware formatters via anIntl.date(pattern).

import 'package:intl/intl.dart';

// Example: Message formatting
String hello(String name) => Intl.message(
  'Hello, $name',
  name: 'hello',
  args: [name],
  desc: 'Say hello',
);

// Example: Setting default locale
Intl.defaultLocale = 'pt_BR';

// Example: Using a specific locale for a block of code
Intl.withLocale('fr', () {
  print(NumberFormat.format(123456));
});

The BidiFormatter class is used to format text that contains both Left-to-Right (LTR) and Right-to-Left (RTL) characters. This prevents layout issues when mixing languages (e.g., embedding English in Hebrew) by either wrapping text in HTML <span> tags or using Unicode BiDi control characters.

Key Capabilities

1. BiDi Wrapping: Automatically wraps text in <span> tags with dir attributes or Unicode markers (LRE/RLE/PDF) to isolate directionality.
2. Directionality Estimation: Automatically detects if a string is LTR or RTL based on its content.
3. HTML Escaping: When generating HTML output, the formatter can automatically escape plain text to prevent XSS.
4. Direction Resetting: Can append Unicode marks (LRM/RLM) to ensure the text following the inserted string returns to the correct context directionality.

// Example: Wrapping text for HTML output in an LTR context
var formatter = BidiFormatter.LTR();
String safeHtml = formatter.wrapWithSpan("Hello (Hebrew: שלום)", isHtml: false);
// Result might look like: <span dir="rtl">שלום</span>

For complex expressions like plurals and genders, you can use Intl.plural and Intl.gender. These can be nested.

Using Intl.plural: You can wrap the plural logic inside an Intl.message call, or if the plural is the top-level requirement of the function, you can call Intl.plural directly and provide the name, args, desc, and examples to it.

Using Intl.gender: Use Intl.gender to provide different message variations based on a gender string (e.g., 'male', 'female', 'other').

// Plural example
remainingEmailsMessage(int howMany, String userName) =>
  Intl.plural(
    howMany,
    zero: 'There are no emails left for $userName.',
    one: 'There is $howMany email left for $userName.',
    other: 'There are $howMany emails left for $userName.',
    name: 'remainingEmailsMessage',
    args: [howMany, userName],
    desc: 'How many emails remain after archiving.',
    examples: const {'howMany': 42, 'userName': 'Fred'});

// Gender example
notOnlineMessage(String userName, String userGender) =>
  Intl.gender(
    userGender,
    male: '$userName is unavailable because he is not online.',
    female: '$userName is unavailable because she is not online.',
    other: '$userName is unavailable because they are not online',
    name: 'notOnlineMessage',
    args: [userName, userGender],
    desc: 'The user is not available to hangout.',
    examples: const {'userGender': 'male', 'userName': 'Fred'});

Localized messages are defined as functions that return an Intl.message call. This allows you to provide metadata for translators, such as a name, description, and examples.

Rules for message strings:

• Use a restricted form of Dart string interpolation: only the function's parameters can be used in simple expressions.
• Local variables and expressions with curly braces {} are not allowed inside the message string.
• If you need to format numbers or dates within a message, format them outside the function and pass the resulting string into the message.

Parameters:

• name: Must match the function name (or ClassName_methodName).
• args: Must match the function's argument list.
• desc: A description for translators.
• examples: A map of example inputs and outputs.

greetingMessage(name) => Intl.message(
    'Hello $name!',
    name: 'greetingMessage',
    args: [name],
    desc: 'Greet the user as they first open the application',
    examples: const {'name': 'Emily'});

print(greetingMessage('Dan'));