FileLangProvider class

A LangProvider implementation that loads translations from a directory.

This class supports loading translations from a directory named "lang" in the root of the project. Inside the "lang" directory, there should be a set of subdirectories, each named after a locale (e.g. "en", "fr", "de", etc.). Each of these directories should contain a set of JSON files, each containing a set of key-value pairs. The keys will be used to look up translations, and the values will be the translations themselves.

Directory Structure

project_root/
└── lang/
    ├── en/
    │   ├── messages.json
    │   ├── validation.json
    │   └── fields.json
    ├── fr/
    │   ├── messages.json
    │   ├── validation.json
    │   └── fields.json
    └── es/
        ├── messages.json
        └── validation.json

JSON File Format

Each JSON file contains key-value pairs:

{
  "greeting": "Hello :name!",
  "items": "item|items",
  "welcome": "Welcome to :app",
  "error_required": "The :field field is required.",
  "apples": "You have :count apple|You have :count apples"
}

Features

  • Automatic loading: Translations are loaded on-demand when first accessed.
  • Fallback support: Falls back to fallback locale if translation not found.
  • Namespace support: Load translations for specific packages or modules.
  • Parameter replacement: Replace :param placeholders with values.
  • Pluralization: Handle singular/plural forms with | separator.
  • Custom replacers: Add custom logic for parameter replacement.
  • Caching: Cache loaded translations to improve performance.

Usage Examples

final provider = FileLangProvider();
provider.setLocale('en');
provider.setFallbackLocale('en');

// Basic translation
String greeting = provider.t('messages.greeting', parameters: {'name': 'Alice'});

// Pluralization
String apples = provider.choice('apples', 3, parameters: {'count': 3});

// Field translation
String label = provider.field('email');

// Namespace loading
provider.loadNamespace('auth', 'en', {'login': 'Sign In'});
String login = provider.t('login', namespace: 'auth');

Parameter Replacement

The provider supports multiple parameter replacement strategies:

  1. Standard replacement: :param is replaced with the parameter value.
  2. Custom replacers: Add functions for complex formatting.
  3. Nested parameters: Parameters can contain objects for complex logic.

Pluralization Rules

  • item|items → "item" for count=1, "items" for count≠1
  • apple|apples → "apple" for count=1, "apples" for count≠1
  • Works with parameters: :count item|:count items

Performance Notes

  • Translations are cached after first load.
  • Use clearCache to force reload after file changes.
  • Large translation files are loaded entirely into memory.
Implemented types

Constructors

FileLangProvider()

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

addParameterReplacer(String replacer(String key, dynamic value, Map<String, dynamic> parameters)) → void
Adds a custom parameter replacer function.
override
choice(String key, int count, {Map<String, dynamic>? parameters, String? locale, String? namespace}) → String
Translates with pluralization based on count.
override
clearCache() → void
Clears any cached translations.
override
field(String key, {String? locale, String? namespace}) → String
Looks up a field translation.
override
get(String key, {String? locale, String? namespace}) → String?
Gets the raw translation value without parameter replacement.
override
getAvailableLocales() → List<String>
Gets all available locales.
override
getFallbackLocale() → String
Gets the fallback locale.
override
getLocale() → String
Gets the current locale.
override
has(String key, {String? locale, String? namespace}) → bool
Checks if a translation key exists.
override
loadNamespace(String namespace, String locale, Map<String, String> translations) → void
Loads translations for a specific namespace.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
setFallbackLocale(String locale) → void
Sets the fallback locale for missing translations.
override
setLocale(String locale) → void
Sets the current locale.
override
t(String key, {Map<String, dynamic>? parameters, String? locale, String? namespace}) → String
Looks up a translation for the given key with advanced parameter replacement.
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited