Skip to content

TRANSLATING.md

Latest commit

 

History

History
108 lines (73 loc) · 6.72 KB

TRANSLATING.md

File metadata and controls

108 lines (73 loc) · 6.72 KB
Raw

Translating FolderView Plus

FolderView Plus uses English as its source catalog and falls back to English whenever a translation is missing. A locale is presented as complete after every current source message is translated, the automated language contracts pass, and the project maintainer accepts it for shipping. Native-speaker feedback remains welcome, but it is not required to ship or retain a complete catalog.

Catalog layout

  • src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/langs/en.json contains legacy messages.
  • src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/langs/namespaces/en/ contains feature-oriented modern messages.
  • src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/langs/<locale>.json contains existing non-English legacy translations.
  • Modern translation scaffolds live under langs/namespaces/<locale>/<namespace>.json; add reviewed messages to the existing locale file instead of copying English into it.
  • legacy-surface.json is generated from remaining static and runtime-written legacy UI text. Do not edit its hashed keys by hand; regenerate it with the repository builder.
  • langs/registry.php records the native language name, direction, and review status used by the runtime loader.

Message keys describe meaning instead of copying English wording. New keys should use a feature namespace, for example docker.privacy.mask-lan-ips or wizard.navigation.review. Do not rename a key solely because the English sentence was edited.

Translation status

  • source: authoritative English source.
  • complete: every current source message is translated, structurally validated, and maintainer accepted for shipping.
  • partial: useful translations exist, but English fallback remains visible for missing or stale messages.
  • placeholder: no reviewed translation is currently shipped. The runtime deliberately loads English instead of an English-copy locale file.

Do not fill untranslated keys with copied English text to increase the apparent completion percentage. Missing keys are the correct representation of unfinished work.

Message rules

  1. Preserve parameters such as $1 and $2 exactly.
  2. Keep supported markup and links equivalent to the English source. Never add scripts, event attributes, or untrusted URLs.
  3. Translate full sentences instead of joining independently translated fragments.
  4. Use {{PLURAL:$1|singular|plural}} where the sentence depends on a count. Languages may provide every plural form supported by jquery.i18n.
  5. Keep product names such as FolderView Plus, Unraid, Docker, and User Scripts unchanged unless an established localized name exists.
  6. Preserve the distinction between Docker containers, virtual machines, folders, members, rules, previews, and backups.

Glossary

English term Meaning in FolderView Plus
Folder A visual organization group; not a filesystem directory.
Member A Docker container, VM, or child folder assigned to a folder.
Rule An automatic assignment condition evaluated by FolderView Plus.
Preview The compact member display shown inside or alongside a folder row.
Runtime page The Unraid Docker, VM, or Dashboard page enhanced by the plugin.
Snapshot A saved FolderView Plus configuration used for compare or recovery.
Import Applying a FolderView/FolderView Plus configuration export.

Validation

Run these repository-provided checks before submitting a translation:

bash scripts/i18n_guard.sh
bash scripts/lang_usage_guard.sh

The guards validate catalog JSON, metadata, duplicate keys, message parameters, plural syntax, HTML consistency, source-code references, unused keys, and zero uncovered user-facing UI strings.

When English legacy UI text changes, regenerate the complete surface catalogs before running the guards:

node scripts/build_i18n_surface_catalogs.mjs --translate

The generator preserves existing translations, translates only new or changed surface messages, protects numbered parameters, updates catalog metadata, and writes the extraction report. Translation is a repository maintenance step; installed plugins never contact a translation service.

Pseudo-locales

After a FolderView Plus page has loaded, use the browser console to test text expansion:

FolderViewPlusI18n.usePseudoLocale('en-XA')

Use the bidirectional pseudo-locale to test right-to-left layout:

FolderViewPlusI18n.usePseudoLocale('ar-XB')

Restore the Unraid-selected locale with:

FolderViewPlusI18n.restoreLocale()

Test Docker, VMs, Dashboard, Settings Basic and Advanced, the Setup Assistant, import dialogs, diagnostics, and the modern folder editor. Look for clipping, fixed-width controls, incorrect icon placement, English strings, and broken keyboard or screen-reader labels.

The repository browser smoke run also activates en-XA and ar-XB, verifies language and direction state, and saves full-page screenshots for expansion and RTL review.

Regional locales

Locale names follow BCP 47. Add a regional file only when the language actually differs, such as pt-BR, pt-PT, zh-Hans, or zh-Hant. The loader resolves the most specific available locale, then its base language, then English.

FolderView Plus currently distinguishes pt-BR, pt-PT, and zh-Hans. Traditional Chinese requests deliberately fall back to English until a reviewed zh-Hant catalog exists; they must never silently receive Simplified Chinese text.

Review workflow

  1. Update the English source and increment the catalog version.
  2. Run the guards and review newly missing translations.
  3. Translate with UI context or screenshots available.
  4. Machine-assisted translation may be used, but preserve product terms, parameters, markup, and locale-specific plural forms.
  5. Run the structural guards and review high-risk wording such as destructive actions, imports, restores, and deletion choices before maintainer acceptance.
  6. Update locale metadata and registry status only after every source key is present and the catalog is accepted for shipping.

The repository is prepared for a Weblate project using the component masks and review controls in TRANSLATION_PLATFORM.md. JSON pull requests remain supported so the project is not dependent on an external translation service.

Coverage and extraction

Diagnostics reports legacy and modern namespace coverage separately, whether a locale was reviewed against the current English source, and the count of translations that may be stale. The generated legacy-surface namespace binds remaining initial and dynamically inserted UI text at runtime. langs/extraction-report.json must report zero uncovered candidates, and the guards fail whenever source UI and the generated namespace drift apart.