localization library

Backwards-compatible entrypoint.

The package's primary entrypoint is anas_localization.dart. Keep this file so older imports (package:anas_localization/localization.dart) continue to work.

Classes

AnasDateTimeFormatter
Provides localized date and time formatting utilities. Uses full locale (e.g. ar_SA, ar_MA) so Arabic weekday/month names and AM/PM labels come from intl. English regional defaults: en_US and en_CA use 12-hour clock; en_GB and en_AU use 24-hour (intl).
AnasDirectionalityWrapper
Widget that automatically handles text direction based on current locale
AnasInterpolation
Advanced interpolation with rich text support
AnasLanguageDialog
A language selector that opens as a dialog with confirmation
AnasLanguageSelector
A pre-built language selector dropdown widget
AnasLanguageSetup
Public API for triggering language changes with setup overlay
AnasLanguageSetupOverlay
A loading overlay that appears during language changes Similar to iPhone's "Setting up language..." screen
AnasLanguageToggle
A simple language toggle button (for apps with 2 languages)
AnasLocaleDetector
Provides automatic locale detection and smart defaults
AnasLocalization
AnasLocalizationScope
Public API contract exposed by AnasLocalization.of.
AnasLocalizationStorage
A utility class for managing the selected locale in local storage.
AnasLocalizationWithSetup
A complete localization provider with language setup overlay
AnasNumberFormatter
Provides localized number and currency formatting. Uses full locale (e.g. ar_SA, ar_MA) so region drives Eastern vs Western numerals and separators (intl). English regions use period decimal and comma thousands (e.g. 1,234.56) via intl.
AnasRichText
Widget for displaying rich localized text
AnasTextDirection
Provides text direction utilities for different locales. English (en, en_US, en_GB, en_CA, en_AU) is explicitly LTR; only RTL languages use RTL.
ApiResponse<T>
REST API response wrapper for consistent responses
ArbInterop
ArbLocaleDocument
ArbTranslationLoader
CatalogActivityEvent
CatalogActivityKinds
CatalogBulkReviewResult
CatalogCellState
CatalogKeyState
CatalogMeta
CatalogReviewTarget
CatalogRow
CatalogState
CatalogStateDto
Catalog state DTO for API serialization
CatalogSummary
CsvTranslationLoader
CustomLocale
Represents a user-defined locale not in the predefined list.
Dictionary
DictionaryLocalizations
DictionaryLocalizationsDelegate
FallbackChain
Represents the complete resolution path for a locale's translations.
FallbackConfigDto
Fallback configuration DTO for API requests/responses
FallbackConfigurationApi
REST API Controller for fallback configuration management
GlobalCupertinoLocalizations
Implementation of localized strings for Cupertino widgets using the intl package for date and time formatting.
GlobalMaterialLocalizations
Implementation of localized strings for the material widgets using the intl package for date and time formatting.
GlobalWidgetsLocalizations
Localized values for widgets.
HttpTranslationLoader
Loads translations from a remote HTTP endpoint.
JsonTranslationLoader
L10nYamlConfig
LanguageGroup
Represents a logical grouping of locales sharing the same base language. Computed dynamically from available locales, not persisted.
LocaleValidationResult
Result of validating a locale code against ISO standards.
LocaleValidationResultDto
Locale validation result DTO
LocaleValidationService
Service for validating locale codes against ISO standards.
LocalizationService
LocalizationTestHelper
Test utilities for localization
NoOpRemoteLocalizationMetrics
PluralRules
Pluralization rules engine for different languages. English uses a num contract: singular only when count.abs() == 1; otherwise plural.
RemoteCheckResponse
RemoteLocalizationCacheSnapshot
RemoteLocalizationCacheStore
RemoteLocalizationConfig
RemoteLocalizationConnector
RemoteLocalizationFailed
RemoteLocalizationFailure
RemoteLocalizationMetrics
RemoteLocalizationNoUpdate
RemoteLocalizationPayload
RemoteLocalizationService
RemoteLocalizationSkippedDuplicate
RemoteLocalizationUnsupported
RemoteLocalizationUpdateResult
RemoteLocalizationUpdateSuccess
RemoteLocalizationVersion
RemoteUpdateDescriptor
RemoteVersionSnapshot
TranslationLoader
Loads translation content from a single source (assets, HTTP, etc.).
TranslationLoaderRegistry
TranslationValidator
Validates translation files for consistency and completeness.
UserContext
Context used for message resolution: locale, gender, formality, regional variant. Defaults: gender = male, regionalVariant = MSA when not set.
ValidationOptions
ValidationResult
Validation results for translation files
ValidationRuleToggles
YamlTranslationLoader

Enums

CatalogCellStatus
DataType
FormalityLevel
Formality level for pronouns and phrasing.
LocaleValidationErrorType
Enumeration of locale validation error types.
RegionalVariant
Regional variant (dialect) for Arabic. Default when not set is MSA.
RemoteLocalizationFailureCode
RemoteLocalizationMetric
RemoteLocalizationScope
RemoteLocalizationUpdateStatus
ResolutionGender
Gender for message resolution; only male or female. Default when not set is male.
ValidationProfile

Extensions

DateTimeFormattingExtension on DateTime
Extension to add date/time formatting to Dictionary
DictionaryResolution on Dictionary
Extension so Dictionary can be resolved with UserContext via the same path as raw-key access (Constitution I).
LocalizationExtension on BuildContext
Extension to make BuildContext-based access even easier
NumberFormattingExtension on BuildContext
Extension to add number formatting to BuildContext
TextDirectionExtension on BuildContext
Extension to add text direction helpers to BuildContext

Constants

defaultDataType → const DataType
Default data type when none is specified (per spec FR-002).
kArabicHonorifics → const Map<String, Map<ResolutionGender, String>>
Default Arabic honorific strings (male/female) for common titles. Keys are normalized lowercase (e.g. "dr", "mr", "mrs", "engineer").
kArabicPhoneRegionCodes → const List<String>
Supported Arabic region codes for phone validation (subset of supportedArabicRegionCodes).
kDefaultArabicNameMaxLength → const int
Default max grapheme length for Arabic name validation (configurable).
kDefaultArabicNameMinLength → const int
Default min length for Arabic name.
kDefaultTranslationLoaders → const List<TranslationLoader>

Properties

anasLanguageSetupOverlayKey → GlobalKey<State<AnasLanguageSetupOverlay>>
Package-internal key used to reference the active AnasLanguageSetupOverlay state without a static instance field.
final
t → dynamic
Global getter for easy access to the current dictionary Usage: t.appName, t.welcomeUser(name: 'John'), etc.
no setter

Functions

catalogCellStatusFromString(String value) → CatalogCellStatus
catalogCellStatusToString(CatalogCellStatus status) → String
dataTypeFromString(String? value) → DataType
Parses a string to DataType; returns defaultDataType for null/empty/unknown.
dataTypeToString(DataType type) → String
Serializes DataType for storage (e.g. in @dataTypes map).
getLanguageCode(String locale) → String
Helper function: extracts language code from a locale. E.g., 'en_US' -> 'en', 'ar_SA' -> 'ar'
hasCircularFallback(Map<String, String> fallbacks, String locale, String newFallback) → bool
Helper function: detects if adding a fallback would create a circular reference. Returns true if adding fallback for locale -> newFallback would cause a cycle.
isReasonablyValidArabicName(String name, {int minLength = kDefaultArabicNameMinLength, int maxLength = kDefaultArabicNameMaxLength}) → bool
Returns true if name is non-empty, within length bounds, and contains only allowed characters: Unicode letters (including Arabic), spaces, and common diacritics. Use minLength/maxLength to override defaults.
isReasonablyValidArabicRegionPhone(String phone, String regionCode, {bool validator(String digits)?}) → bool
Returns true if phone looks like a valid number for regionCode (e.g. SA, EG). Uses a simple length and digit check; for strict E.164 or national format use a dedicated library (e.g. libphonenumber) or pass a custom validator.
normalizeForSearch(String text) → String
Normalizes text for search matching: strips combining marks (diacritics) so that queries match regardless of tashkeel. For hamza equivalence or full NFD, consider using package:unicode or platform collation.
resolveFallbackChain(Map<String, String> fallbacks, String locale) → List<String>
Helper function: resolves the full fallback chain for a locale. Returns list of locales in fallback order: primary, fallback1, fallback2, ...
resolveHonorific(String title, ResolutionGender gender, {String? nameOnly, String unknownLabel = ''}) → String
Resolves an honorific title with gender to a localized string (e.g. Arabic). title is normalized (trimmed, lowercased, dots removed); if it matches a known key in kArabicHonorifics, returns the corresponding male/female string; otherwise returns nameOnly (show name only) or unknownLabel if nameOnly is null/empty.
resolveMessage(Dictionary dictionary, UserContext context, {required String key, UserContext? overrides, Map<String, dynamic>? params}) → String
Resolves a message key using dictionary, context, and optional overrides and params. Implements canonical fallback: within same key try alternate form (plural→other, gender→other, variant→MSA), then base/key.
sameLanguageGroup(String locale1, String locale2) → bool
Helper function: checks if two locales share the same language group. Same language group if they have the same language code, or one is a language-only code.
sortWithLocale(List<String> list, int compare(String a, String b)) → void
Sorts list in place using compare. For locale-aware Arabic sort, use a collation API (e.g. intl4x Collation or platform) and pass its compare; this helper documents the pattern.

Typedefs

TranslationMap = Map<String, dynamic>

Exceptions / Errors

CircularFallbackException
Exception thrown when configuring a language group fallback would create a cycle.
InvalidLocaleCodeException
Exception thrown when an invalid locale code is provided.
LocalizationAssetsNotFoundException
Thrown when no localization assets can be resolved for a locale.
LocalizationException
Base class for localization-related failures.
LocalizationNotInitializedException
Thrown when locale-dependent state is requested before initialization.
RemoteTranslationLoadException
Thrown when a remote translation loader fails due to transport or parse errors.
UnsupportedLocaleException
Thrown when a locale is requested that is not in the configured supported locales.