> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lopiv2/invenicum/llms.txt
> Use this file to discover all available pages before exploring further.

# Internationalization (i18n)

> Configure language settings, add translations, and manage multi-language support in Invenicum

## Overview

Invenicum supports multiple languages out of the box with Flutter's built-in internationalization (i18n) system. Users can switch languages on-the-fly, and all UI text adapts automatically.

## Supported Languages

Invenicum currently supports **6 languages**:

| Language   | Code | Native Name |
| ---------- | ---- | ----------- |
| English    | `en` | English     |
| Spanish    | `es` | Español     |
| Italian    | `it` | Italiano    |
| Portuguese | `pt` | Português   |
| French     | `fr` | Français    |
| German     | `de` | Deutsch     |

<Info>
  The default language is **Spanish** (`es`), but this changes based on user preferences.
</Info>

## Localization Configuration

### l10n.yaml

The localization setup is defined in `l10n.yaml:1-11`:

```yaml theme={null}
arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
untranslated-messages-file: missing_translations.txt
supported-locales:
  - en
  - es
  - it
  - pt
  - fr
  - de
```

### pubspec.yaml

Localization dependencies are configured in `pubspec.yaml:33-45`:

```yaml theme={null}
dependencies:
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true  # Enables automatic code generation
```

### main.dart

Localization delegates are registered in `main.dart:296-304`:

```dart theme={null}
MaterialApp.router(
  locale: preferencesProvider.locale,
  localizationsDelegates: const [
    AppLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: AppLocalizations.supportedLocales,
  // ...
)
```

## Translation Files

Translation files are stored in ARB (Application Resource Bundle) format:

```
lib/l10n/
├── app_en.arb  (English - Template)
├── app_es.arb  (Spanish)
├── app_it.arb  (Italian)
├── app_pt.arb  (Portuguese)
├── app_fr.arb  (French)
└── app_de.arb  (German)
```

### ARB File Structure

**File:** `lib/l10n/app_en.arb:1-493`

Example entries:

```json theme={null}
{
  "@@locale": "en",
  
  "appTitle": "Invenicum Inventory",
  "dashboard": "Dashboard",
  "settings": "Settings",
  "language": "Language",
  "currency": "Currency",
  
  "@fieldRequiredWithName": {
    "placeholders": {
      "field": {
        "type": "String"
      }
    }
  },
  "fieldRequiredWithName": "Field \"{field}\" is required.",
  
  "integrationGeminiDesc": "Connect Invenicum with Google's Gemini to leverage advanced AI capabilities in managing your inventory.",
  "helperGeminiKey": "Enter your Gemini API key to enable integration. Get it at https://aistudio.google.com/"
}
```

<Note>
  Entries starting with `@` define metadata like placeholders. The actual translation follows with the same key minus the `@`.
</Note>

## Changing Language

### User Interface

<Steps>
  <Step title="Open Settings">
    Navigate to **Settings** → **General Settings**
  </Step>

  <Step title="Find Language Section">
    Locate the **Language** option with globe icon
  </Step>

  <Step title="Select Language">
    Click the dropdown and choose your preferred language:

    * English
    * Español (Spanish)
    * Italiano (Italian)
    * Português (Portuguese)
    * Français (French)
    * Deutsch (German)
  </Step>

  <Step title="Confirm Change">
    The app will update immediately and show:

    ```
    Language changed to English!
    ```
  </Step>
</Steps>

### Programmatic Usage

**Preferences Provider:** `lib/providers/preferences_provider.dart`

```dart theme={null}
// Get current locale
Locale get locale => Locale(_prefs.language);

// Change language
Future<void> setLanguage(String languageCode) async {
  _prefs = _prefs.copyWith(language: languageCode);
  await _preferencesService.updateLanguage(languageCode);
  notifyListeners();
}
```

**Preferences Service:** `lib/data/services/preferences_service.dart:42-48`

```dart theme={null}
Future<void> updateLanguage(String languageCode) async {
  await _dio.put('/preferences/language', 
    data: {'language': languageCode}
  );
}
```

**API Endpoint:** `PUT /api/v1/preferences/language`

```json theme={null}
{
  "language": "en"
}
```

## Using Translations in Code

### Access Localizations

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:invenicum/l10n/app_localizations.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Get localizations instance
    final l10n = AppLocalizations.of(context)!;
    
    return Text(l10n.dashboard);  // "Dashboard" in selected language
  }
}
```

### Simple Strings

```dart theme={null}
Text(AppLocalizations.of(context)!.settings)
Text(AppLocalizations.of(context)!.language)
Text(AppLocalizations.of(context)!.currency)
```

### Strings with Placeholders

```dart theme={null}
// ARB definition
{
  "fieldRequiredWithName": "Field \"{field}\" is required."
}

// Usage
AppLocalizations.of(context)!.fieldRequiredWithName("Email")
// Output: "Field \"Email\" is required."

AppLocalizations.of(context)!.veniChatProcessing("inventory status")
// Output: "I'm processing your query about \"inventory status\"..."
```

### Integration-Specific Translations

```dart theme={null}
final l10n = AppLocalizations.of(context)!;

IntegrationConfig(
  id: 'gemini',
  name: 'Google Gemini AI',
  description: l10n.integrationGeminiDesc,
  fields: [
    ConfigField(
      helperText: l10n.helperGeminiKey,
      label: l10n.geminiLabelModel,
    ),
  ],
)
```

## Adding New Translations

<Steps>
  <Step title="Add to English Template">
    Edit `lib/l10n/app_en.arb` and add your new key:

    ```json theme={null}
    {
      "myNewFeature": "My New Feature",
      "welcomeMessage": "Welcome, {userName}!",
      
      "@welcomeMessage": {
        "placeholders": {
          "userName": {
            "type": "String"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Add to All Language Files">
    Add the same keys to all other ARB files:

    * `app_es.arb`: `"myNewFeature": "Mi Nueva Función"`
    * `app_it.arb`: `"myNewFeature": "La Mia Nuova Funzione"`
    * `app_pt.arb`: `"myNewFeature": "Meu Novo Recurso"`
    * `app_fr.arb`: `"myNewFeature": "Ma Nouvelle Fonctionnalité"`
    * `app_de.arb`: `"myNewFeature": "Meine Neue Funktion"`
  </Step>

  <Step title="Generate Code">
    Run Flutter's code generator:

    ```bash theme={null}
    flutter gen-l10n
    ```

    Or simply build/run the app:

    ```bash theme={null}
    flutter run
    ```

    This generates `lib/l10n/app_localizations.dart` and language-specific classes.
  </Step>

  <Step title="Use in Code">
    ```dart theme={null}
    Text(AppLocalizations.of(context)!.myNewFeature)
    Text(AppLocalizations.of(context)!.welcomeMessage(user.name))
    ```
  </Step>
</Steps>

## Adding a New Language

<Steps>
  <Step title="Update l10n.yaml">
    Add the new locale code to `supported-locales`:

    ```yaml theme={null}
    supported-locales:
      - en
      - es
      - it
      - pt
      - fr
      - de
      - ja  # Japanese (new)
    ```
  </Step>

  <Step title="Create ARB File">
    Create `lib/l10n/app_ja.arb`:

    ```json theme={null}
    {
      "@@locale": "ja",
      "appTitle": "Invenicum インベントリ",
      "dashboard": "ダッシュボード",
      "settings": "設定",
      // ... translate all keys from app_en.arb
    }
    ```
  </Step>

  <Step title="Update Language Dropdown">
    Add the language option to the language selection UI in your settings screen.
  </Step>

  <Step title="Generate and Test">
    ```bash theme={null}
    flutter gen-l10n
    flutter run
    ```
  </Step>
</Steps>

## RTL (Right-to-Left) Support

<Warning>
  **RTL languages** like Arabic or Hebrew are **not currently implemented** in Invenicum. The framework supports RTL, but the app has not been tested with RTL locales.
</Warning>

To add RTL support in the future:

1. Add RTL locale to `l10n.yaml` (e.g., `ar` for Arabic)
2. Create ARB file with translations
3. Flutter automatically handles text direction based on locale
4. Test all UI layouts for RTL compatibility

```dart theme={null}
// Flutter automatically sets text direction
Text('مرحبا')  // Displays right-to-left for Arabic locale
```

## Best Practices

<Tip>
  **Use descriptive keys:** Instead of `text1`, use `dashboardTitle` or `errorLoadingData`.
</Tip>

<Tip>
  **Keep translations in sync:** When adding a new key, update **all** language files to avoid missing translations.
</Tip>

<Warning>
  **Avoid hardcoded strings:** Always use `AppLocalizations` for user-facing text, even for placeholders and error messages.
</Warning>

<Info>
  **Missing translations:** The `missing_translations.txt` file will list any keys missing from language files after code generation.
</Info>

## Generated Files

Do not edit these files manually (they're auto-generated):

* `lib/l10n/app_localizations.dart` - Base class
* `lib/l10n/app_localizations_en.dart` - English
* `lib/l10n/app_localizations_es.dart` - Spanish
* `lib/l10n/app_localizations_it.dart` - Italian
* `lib/l10n/app_localizations_pt.dart` - Portuguese
* `lib/l10n/app_localizations_fr.dart` - French
* `lib/l10n/app_localizations_de.dart` - German

## Related Documentation

* [Flutter Internationalization Guide](https://docs.flutter.dev/ui/accessibility-and-localization/internationalization)
* [ARB File Format](https://github.com/google/app-resource-bundle)
* [User Preferences](/configuration/environment)