Skip to content

feat(i18n): support per-locale UI string overrides - #40

Open
mathis6787 wants to merge 1 commit into
nexlabstudio:devfrom
mathis6787:fix/missing-translation
Open

feat(i18n): support per-locale UI string overrides#40
mathis6787 wants to merge 1 commit into
nexlabstudio:devfrom
mathis6787:fix/missing-translation

Conversation

@mathis6787

Copy link
Copy Markdown

Summary

Adds per-locale UI string overrides and localizes previously hardcoded Stardust interface text.

Before this change, i18n.strings was shared by every locale. Multi-locale sites could not provide different UI strings for each language without client-side JavaScript workarounds.

Changes

  • Add an optional strings map to each locale.
  • Merge partial locale strings with the shared i18n.strings fallback.
  • Resolve strings using the active locale or configured default locale.
  • Add localization keys for:
    • Search placeholder
    • Table-of-contents title
    • Code-copy labels and feedback
    • Copy-page-as-Markdown label
    • Dartdoc API and back-to-docs labels
  • Use the existing search.searching string during search.
  • Preserve the original image alt text in the zoom overlay.
  • Update the JSON schema, generated Dart schema, and i18n documentation.
  • Add configuration, rendering, Dartdoc, and CLI test coverage.

Example

i18n:
  enabled: true
  defaultLocale: en

  # Optional strings shared by all locales.
  strings:
    footer.poweredBy: "Documentation by"

  locales:
    - code: en
      label: English
      path: /

    - code: fr
      label: Français
      path: /fr/
      strings:
        nav.previous: "← Précédent"
        nav.next: "Suivant →"
        search.placeholder: "Rechercher…"
        search.searching: "Recherche…"
        toc.title: "Sur cette page"
        code.copy: "Copier"
        code.copyLabel: "Copier le code"
        code.copied: "Copié !"
        code.copyFailed: "Échec de la copie"
        page.copyMarkdown: "Copier en Markdown"

Potential follow-up improvements

This PR intentionally preserves SearchConfig.placeholder and
TocConfig.title to maintain compatibility with existing configurations.

In the future, it may be cleaner to move all user-facing defaults—including
"Search docs..." and "On this page"—into I18nStrings. SearchConfig
would then contain only search behavior, while TocConfig would contain only
table-of-contents behavior.

After centralizing all user-facing defaults in I18nStrings, a subsequent
improvement could move the built-in translations out of i18n_config.dart and
into external locale catalogs, for example:

stardust-theme-translations/
└── locales/
    ├── en.json
    ├── fr.json
    ├── es.json
    └── ar.json

I would be interested in working on these follow-up improvements if this
direction is accepted. I am also open to suggestions !

- Added i18nStrings schema definition to support localization.
- Updated stardust_schema.dart to include i18nStrings reference.
- Enhanced MarkdownParser to utilize localized copy button text and aria-label.
- Modified DartdocGenerator to use localized API and back-to-docs labels.
- Updated PageLayoutBuilder to reflect localized search placeholder and TOC title.
- Enhanced PageScriptsBuilder to include localized runtime strings for copy feedback.
- Updated PageBuilder to use localized copy-page Markdown label.
- Added tests to ensure proper parsing and application of localized strings.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant