Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Cristiang1021/ErgoKawsay/llms.txt

Use this file to discover all available pages before exploring further.

All UI strings in ErgoKawsay are centralized in translations.yaml. A Python generator script reads the YAML and writes a Dart constant class. This approach keeps translations in plain text, making them reviewable and editable by translators, educators, and linguists without any knowledge of Dart or Flutter.

​
File Layout

FileRole
translations.yamlSource of truth for all Spanish and Kichwa strings
tools/gen_translations.pyPython 3 script that reads the YAML and writes tr.dart
lib/core/localization/tr.dartAuto-generated Dart constant class — do not edit manually

​
YAML Format

Each UI string is nested under a feature namespace. The leaf node holds es and kichwa sub-keys. Nesting can be as deep as needed to reflect the feature hierarchy: 
active_breaks:
  title:
    es: "PAUSAS ACTIVAS"
    kichwa: "Llamkaypi samariy"
  neck_rotation:
    es: "Rotación de cuello"
    kichwa: "Kunkata muyuchiy"

reminders:
  night_silence:
    es: "Modo Silencio nocturno"
    kichwa: "Tuta chulun pacha"
  night_silence_hours:
    es: "20:00-06:00 sin notificaciones"
    kichwa: "20:00-06:00 nima willay tiyana kan"
The generator converts nested YAML keys to camelCase Dart identifiers. For example, active_breaks.neck_rotation becomes activeBreaksNeckRotation, and the two variants are suffixed Es and Qu.

​
Generated Dart Output

The generator writes lib/core/localization/tr.dart as an abstract final class Tr with static const String fields and static helper methods: 
// lib/core/localization/tr.dart (auto-generated — do not edit by hand)
abstract final class Tr {
  Tr._();

  static String pick(bool isKichwa, String es, String qu) =>
      isKichwa ? qu : es;

  static const String activeBreaksTitleEs = "Pausas Activas";
  static const String activeBreaksTitleQu = "Llamkaypi samariy";

  static const String activeBreaksNeckRotationEs = "Rotación de cuello";
  static const String activeBreaksNeckRotationQu = "Kunkata muyuchiy";

  // ...

  static String activeBreaksTitle(bool isKichwa) =>
      pick(isKichwa, activeBreaksTitleEs, activeBreaksTitleQu);

  static String activeBreaksNeckRotation(bool isKichwa) =>
      pick(isKichwa, activeBreaksNeckRotationEs, activeBreaksNeckRotationQu);
}
Every leaf becomes:
  • Two static const String fields (Es and Qu suffixes)
  • One static method that accepts bool isKichwa and delegates to pick()

​
Adding a New String

1

Open translations.yaml

Open translations.yaml at the project root in any text editor.
2

Add the key with both language values

Place the new key under the appropriate feature namespace. Both es and kichwa sub-keys are required — the generator will fail if either is missing:
settings:
  new_feature_label:
    es: "Nueva función"
    kichwa: "Mushuk rurashka"
3

Run the generator

From the project root:
python tools/gen_translations.py
The script prints the number of entries written and overwrites lib/core/localization/tr.dart.
4

Use the new constant in code

Import tr.dart and reference the generated constants:
import 'package:ergokawsay/core/localization/tr.dart';

Text(Tr.settingsNewFeatureLabelEs)                    // direct
Text(Tr.settingsNewFeatureLabel(isKichwa))            // via helper
Text(Tr.pick(isKichwa,
      Tr.settingsNewFeatureLabelEs,
      Tr.settingsNewFeatureLabelQu))                  // explicit pick

​
Generator Script

The script at tools/gen_translations.py uses Python 3 and PyYAML. It:
  1. Reads translations.yaml from the project root.
  2. Recursively walks the translations: tree, collecting leaf nodes that have both es and kichwa keys.
  3. Converts the YAML key path (e.g., ['active_breaks', 'neck_rotation']) to a camelCase Dart identifier (activeBreaksNeckRotation).
  4. Writes lib/core/localization/tr.dart with the abstract final class Tr body.
Install the dependency and run: 
pip install pyyaml
python tools/gen_translations.py
The script is deterministic — the same YAML always produces the same Dart file. It does not require the Flutter SDK.

​
Translation Review Process

translations.yaml is plain text and version-controlled alongside the source code. Translators can review and update strings without opening an IDE:
  • Spanish strings provide the reference meaning.
  • Kichwa translations were developed in the context of the ESPOCH academic project, using vocabulary appropriate for the Andean pedagogical context (e.g., "Alli kawsay" for well-being, "Yachachik" for teacher).
Suggested review workflow: open a pull request with only translations.yaml changes, have a Kichwa-speaking reviewer approve the strings, then regenerate tr.dart as a follow-up commit.
Never edit lib/core/localization/tr.dart directly. Any manual changes will be lost the next time python tools/gen_translations.py is run, which overwrites the entire file.

​
Locale Switching at Runtime

LocaleController.setLocale(String code) switches all UI strings immediately. The controller persists the choice to StorageService and calls notifyListeners(), which triggers a full rebuild of MaterialApp with the new Locale. No app restart is required. 
// Switch to Kichwa
context.read<LocaleController>().setLocale('qu');

// Switch to Spanish
context.read<LocaleController>().setLocale('es');
Because Tr constants are resolved at build time (not compile time), the widget tree re-reads the correct string for the new locale on its next build() call.

Build docs developers (and LLMs) love

Get started for freeTalk to us