docs: add documentation for some files

lib/src/core/utils/gen/localization/app_locales.dart

@@ -1,5 +1,12 @@
 import 'dart:ui' show Locale;
 
+/// [AppLocales] class manages app localization.
+///
+/// - [translationsPath] : Path to translation files (`lib/l10n`).
+/// - [supportedLocales] : List of supported locales, generated from available
+/// translations (e.g., `enUSLocale`, `frFRLocale`, `esESLocale`).
+///
+/// The class can be extended by adding more locales as needed.
 class AppLocales {
   AppLocales._();
 

lib/src/core/utils/gen/localization/codegen_loader.dart

@@ -1,5 +1,15 @@
 import 'dart:ui' show Locale;
 
+/// [CodegenLoader] class loads translations for different locales.
+///
+/// - [load] : Loads translation data based on the provided locale.
+/// - [mapLocales] : Maps locales (e.g., `en_US`, `fr_FR`, `es_ES`) to their respective translation data.
+///
+/// Example translations include:
+/// - `enUS`: English translations.
+/// - `frFR`: French translations.
+/// - `esES`: Spanish translations.
+///
 class CodegenLoader {
   const CodegenLoader();
 

lib/src/core/utils/gen/localization/customized_localization_addon.dart

@@ -1,6 +1,34 @@
 import 'package:widgetbook/widgetbook.dart';
 import 'package:flutter/widgets.dart';
 
+/// [CustomizedLocalizationAddon] is an addon used in Widgetbook for customizing
+/// the locale settings of a widget preview.
+///
+/// This addon allows you to:
+/// - Define a list of supported locales.
+/// - Specify the localization delegates for each locale.
+/// - Set an initial locale (optional).
+///
+/// **Parameters:**
+/// - [locales] : List of supported locales (e.g., `en_US`, `fr_FR`).
+/// - [localizationsDelegates] : List of localization delegates to handle translations for each locale.
+/// - [initialLocale] : The starting locale, which defaults to the first locale in the list if not provided.
+///
+/// **Usage:**
+/// Add this addon to your Widgetbook setup to enable locale switching and test widgets in different languages.
+///
+/// Example:
+/// ```dart
+/// CustomizedLocalizationAddon(
+///   locales: [Locale('en', 'US'), Locale('fr', 'FR')],
+///   localizationsDelegates: [
+///     GlobalMaterialLocalizations.delegate,
+///     GlobalWidgetsLocalizations.delegate,
+///   ],
+///   initialLocale: Locale('en', 'US'),
+/// );
+/// ```
+///
 class CustomizedLocalizationAddon extends WidgetbookAddon<Locale> {
   CustomizedLocalizationAddon({
     required this.locales,

lib/src/core/utils/gen/localization/translations_utils.dart

@@ -3,6 +3,28 @@ import 'dart:io';
 import 'dart:developer';
 import 'package:pactus_gui_widgetbook/src/features/main/language/core/language_constants.dart';
 
+/// This script generates the necessary files to support localization in your Flutter app.
+///
+/// The main purpose of this code is to:
+/// - Load ARB translation files (in `lib/l10n` directory) for different locales.
+/// - Generate the `LocaleKeys` class, `CodegenLoader` class, and `AppLocales` class dynamically based on the ARB files.
+/// - Create files to store the translations and helper code required for proper localization in the app.
+///
+/// **Flow:**
+/// 1. Loads translations from ARB files for various locales (e.g., `en_US`, `fr_FR`, `es_ES`).
+/// 2. Generates the `LocaleKeys` class, which contains constants for each key in the translations.
+/// 3. Generates the `CodegenLoader` class to load translations based on the current locale.
+/// 4. Generates the `AppLocales` class, which contains locale constants and the supported locales list.
+///
+/// **Generated Files:**
+/// - `locale_keys.dart`: Contains constants for every key found in the ARB files (e.g., `LocaleKeys.app_name`).
+/// - `codegen_loader.dart`: Provides a loader for translations for different locales.
+/// - `app_locales.dart`: Contains static constants for each supported locale and their associated settings.
+///
+/// **Usage:**
+/// - Ensure you have the correct ARB files in the `lib/l10n` directory with language-country-specific naming (e.g., `app_en.arb` for English).
+/// - Run this script to generate the required localization files. These files will help manage and load translations dynamically in the app.
+
 /// ARB files directory and output file paths
 const arbDir = 'lib/l10n';
 const outputCodegenLoaderFilePath =
@@ -34,6 +56,17 @@ Future<void> _generateAppLocalesClass() async {
   final buffer = StringBuffer();
   buffer.writeln('import \'dart:ui\' show Locale;');
   buffer.writeln();
+  buffer.writeln('/// [AppLocales] class manages app localization.');
+  buffer.writeln('///');
+  buffer.writeln(
+      '/// - [translationsPath] : Path to translation files (`lib/l10n`).');
+  buffer.writeln(
+      '/// - [supportedLocales] : List of supported locales, generated from available');
+  buffer.writeln(
+      '/// translations (e.g., `enUSLocale`, `frFRLocale`, `esESLocale`).');
+  buffer.writeln('///');
+  buffer.writeln(
+      '/// The class can be extended by adding more locales as needed.');
   buffer.writeln('class AppLocales {');
   buffer.writeln('  AppLocales._();\n');
   buffer.writeln('  static const translationsPath = \'$translationsPath\';\n');
@@ -42,7 +75,7 @@ Future<void> _generateAppLocalesClass() async {
   for (var locale in languageCases) {
     final localeConstName = '${locale.language}${locale.country}Locale';
     buffer.writeln(
-      '  static const $localeConstName = Locale("${locale.language}", "${locale.country}");',
+      '  static const $localeConstName = Locale(\'${locale.language}\', \'${locale.country}\');',
     );
   }
 
@@ -133,6 +166,19 @@ Future<void> _generateCodegenLoaderFile(
   final buffer = StringBuffer()
     ..writeln('import \'dart:ui\' show Locale;')
     ..writeln()
+    ..writeln(
+        '/// [CodegenLoader] class loads translations for different locales.')
+    ..writeln('///')
+    ..writeln(
+        '/// - [load] : Loads translation data based on the provided locale.')
+    ..writeln(
+        '/// - [mapLocales] : Maps locales (e.g., `en_US`, `fr_FR`, `es_ES`) to their respective translation data.')
+    ..writeln('///')
+    ..writeln('/// Example translations include:')
+    ..writeln('/// - `enUS`: English translations.')
+    ..writeln('/// - `frFR`: French translations.')
+    ..writeln('/// - `esES`: Spanish translations.')
+    ..writeln('///')
     ..writeln('class CodegenLoader {')
     ..writeln('  const CodegenLoader();')
     ..writeln()

lib/src/features/main/language/core/language_constants.dart

@@ -1,5 +1,28 @@
 import 'package:pactus_gui_widgetbook/src/features/main/language/data/language_case.dart';
 
+/// [LanguageConstants] Documentation
+/// This class defines the language constants for localization in the application.
+///
+/// The `LanguageConstants` class holds predefined `LanguageCase` instances for supported locales.
+/// Each `LanguageCase` includes information about the language, country, and language name.
+///
+/// **Fields:**
+/// - [enUS] : Represents English (United States).
+/// - [frFR] : Represents French (France).
+/// - [esES] : Represents Spanish (Spain).
+///
+/// **List of Supported Languages:**
+/// - [languageCases] : A list containing all the defined language cases (`enUS`, `frFR`, `esES`).
+///
+/// **Usage:**
+/// - This class provides easy access to different languages and locales.
+/// - It is used to manage the list of supported locales for your app, which helps in dynamically loading and switching between languages.
+///
+/// **LanguageCase Structure:**
+/// Each `LanguageCase` consists of:
+/// - `country`: The country code (e.g., 'US', 'FR', 'ES').
+/// - `language`: The language code (e.g., 'en', 'fr', 'es').
+/// - `name`: The name of the language (e.g., 'English', 'Français', 'Español').
 class LanguageConstants {
   LanguageConstants._();
   static final LanguageCase enUS = LanguageCase(

lib/src/features/main/language/core/localization_extension.dart

@@ -1,7 +1,32 @@
 import 'package:flutter/material.dart';
 import 'package:pactus_gui_widgetbook/src/core/utils/gen/localization/codegen_loader.dart';
 
+/// [LocalizationExtension] documentation:
+/// An extension on `BuildContext` that provides easy access to localized strings.
+///
+/// This extension adds a `tr` method to the `BuildContext` class, which is used to retrieve translated
+/// strings based on a provided key. It allows for dynamic localization support in the app.
+///
 extension LocalizationExtension on BuildContext {
+  /// ** [tr] Method:**
+  /// - `tr(String key)`: Retrieves the localized string corresponding to the provided `key`.
+  ///   - The `key` represents a unique identifier for the localized string.
+  ///   - The method first checks the current locale using `Localizations.localeOf(this)` to determine which locale's translations should be used.
+  ///   - It then looks up the key in the `CodegenLoader.mapLocales` map for the appropriate locale (e.g., `en_US`, `fr_FR`, `es_ES`).
+  ///   - If the key is found in the locale map, the corresponding translation is returned.
+  ///   - If no translation is found for the key, the method returns the original `key` as a fallback.
+  ///
+  /// **Usage:**
+  /// This extension allows developers to easily retrieve translations in their app by calling `tr` on the `BuildContext` object, as shown below:
+  /// ```dart
+  /// String translatedText = context.tr(LocaleKeys.app_name);
+  /// ```
+  /// The above call will retrieve the translation for the `app_name` key in the current locale, if it exists. Instead of using the raw key as a string, you can use constants from the `LocaleKeys` class, which is automatically generated from the ARB files.
+  ///
+  /// **Example:**
+  /// If the current locale is `en_US` and the `app_name` key exists in the `en_US` locale, `tr(LocaleKeys.app_name)` will return the English translation, such as `"Pactus GUI (EN)"` if it is defined in the ARB file.
+  /// If no translation is found, it will return the key itself, such as `'app_name'`.
+  ///
   String tr(String key) {
     final locale = Localizations.localeOf(this);
     final localeMap = CodegenLoader

lib/src/features/main/language/data/language_case.dart

@@ -1,3 +1,23 @@
+/// The [LanguageCase] class represents a language and country combination.
+///
+/// It provides a lightweight alternative to the `Locale` object in Flutter,
+/// making it ideal for use cases where only the language and country code are
+/// required. This class is useful when you need to pass language-specific data
+/// across widgets or handle localization logic without the full overhead of a `Locale` object.
+///
+/// **Constructor:**
+/// ```dart
+/// LanguageCase({
+///   required this.name,
+///   required this.language,
+///   required this.country,
+/// });
+/// ```
+///
+/// - [name] : A human-readable name for the language (e.g., `"English"`).
+/// - [language] : The ISO 639-1 language code (e.g., `"en"` for English).
+/// - [country] : The ISO 3166-1 alpha-2 country code (e.g., `"US"` for the United States).
+///
 class LanguageCase {
   LanguageCase({
     required this.name,