Feature Request: Move hardcoded UI strings to a proper internationalization (i18n) system

[skrashevich]

Feature request: Internationalization support and moving hardcoded strings

I apologize for the issue text written with the LLM: English isn't my native language, and in this form it'll be easier to understand my point :)

Current status:
All UI strings are currently hardcoded in English directly in Dart code inside widgets. Examples:

• 'Followers', 'Routes', 'Detection Sensor Log', and more.

Problem:
This makes it impossible to quickly translate the interface into other languages (for example, German, Ukrainian, Russian). The standard Flutter solution is to move all strings to a formal internationalization system that allows easy translations.

What needs to be done:

1. Set up the standard Flutter localization infrastructure (flutter_localizations, .arb files, flutter_gen, etc.).
2. Extract all UI strings (labels, hints, messages, titles, etc.) from code into a separate file (e.g., app_en.arb).
3. Replace string literals with calls to the translation system, e.g., AppLocalizations.of(context)!.followers.
4. Add ARB files for other languages (e.g., app_ru.arb for Russian) as needed to streamline translation.
5. Set up automatic generation of translations and connect the support in MaterialApp/CupertinoApp.

Benefits:

• Enables translating the UI to other languages without touching business logic or UI code.
• Makes it easier to maintain and expand the app for non-English users.
• Improves architecture and frontend scalability.

Example tasks:

• Create an l10n.yaml config file.
• Extract all strings from the <lib/features/> directory into app_en.arb.
• Replace Text('Followers') with Text(AppLocalizations.of(context)!.followers) and similar.
• Set up the build system for automatic translation generation.

Bonus:
Once set up, adding new languages is easy: just create a new .arb file with translations without touching UI code.

[gotnull]

Thanks for the well-structured request — and the English is perfectly clear, no apology needed.

Internationalization is on our roadmap and we agree it's overdue. The codebase currently has ~900 Dart files across 44 feature modules with all UI strings hardcoded in English, so at first glance it looks like a massive multi-month effort.

But honestly, in today's world with LLM-powered coding agents, the bulk of this work - extracting hundreds of string literals, generating ARB keys, replacing Text('Followers') with Text(AppLocalizations.of(context)!.followers) across 900 files - is exactly the kind of mechanical, high-volume transformation that AI agents excel at. The real intellectual work is smaller:

1. Infrastructure setup - l10n.yaml, flutter_localizations, wiring into MaterialApp (one-time, small)
2. Key naming convention - establishing a consistent pattern for ARB keys across 44 feature modules
3. Solving the context-free pattern - we have enums and model classes with displayLabel getters that return English strings outside of widget BuildContext, which needs a clean design solution
4. The actual extraction - this is the "900 files" part that sounds enormous, but it's repetitive pattern matching and replacement - exactly what an LLM agent can grind through efficiently

So rather than a cautious multi-quarter rollout, we're planning to tackle this in a concentrated sprint:

• Week 1: Infrastructure + naming conventions + design pattern for context-free strings. First batch of core screens extracted to establish the pattern.
• Weeks 2–3: Systematic extraction across all remaining feature modules, reviewed in batches.
• Week 4: English .arb published as the translation template, language picker added to Settings, lint rules enforced so no new hardcoded strings can slip in.

A few things that will be excluded: generated protobuf code (lib/generated/) and protocol-level strings (channel names, node shortnames, etc. that come from the mesh radio itself - those aren't ours to translate).

Once the app_en.arb base file is ready, community-contributed translations would be very welcome - and frankly, LLMs can produce solid first-draft translations too, with a native speaker doing a review pass for naturalness and technical accuracy. So if you'd be willing to review Ukrainian and/or Russian translations when the time comes, that would be hugely valuable.

[skrashevich]

Thank you for the prompt response.
I am ready to perform the translation into Russian manually, without an LLM (recently my Russian translation was integrated into the official iOS app Meshtastic; I have an good skill for translating technical English to Russian, but not vice verse :( ).

[gotnull]

Thank you for the prompt response. I am ready to perform the translation into Russian manually, without an LLM (recently my Russian translation was integrated into the official iOS app Meshtastic; I have an good skill for translating technical English to Russian, but not vice verse :( ).

That's great to hear and congrats on the Meshtastic iOS Russian translation, that's exactly the kind of experience that makes for quality localization work.

Here's the plan: when we ship the i18n infrastructure, the first Russian translation will be LLM-generated from the annotated English .arb file. LLMs are decent at technical translation but they're not native speakers - mesh networking terminology and natural-sounding UI copy are areas where they'll likely miss nuance.

That's where your expertise comes in. Once the app_ru.arb file exists, you can review and refine it by submitting a PR against the file at lib/l10n/app_ru.arb. Every string is a simple key-value pair in JSON, so you don't need to touch any Dart code - just edit the translation values and open a PR. We'll have a CONTRIBUTING_TRANSLATIONS.md guide with the full workflow.

If PRs aren't your preferred workflow, you could also just open an issue with the corrected strings and we'll update the file. Whatever works best for you.

We'll ping this issue when the infrastructure is ready and the first-draft app_ru.arb is available for review.

[skrashevich]

Thank you for the prompt response. I am ready to perform the translation into Russian manually, without an LLM (recently my Russian translation was integrated into the official iOS app Meshtastic; I have an good skill for translating technical English to Russian, but not vice verse :( ).

That's great to hear and congrats on the Meshtastic iOS Russian translation, that's exactly the kind of experience that makes for quality localization work.

Here's the plan: when we ship the i18n infrastructure, the first Russian translation will be LLM-generated from the annotated English .arb file. LLMs are decent at technical translation but they're not native speakers - mesh networking terminology and natural-sounding UI copy are areas where they'll likely miss nuance.

That's where your expertise comes in. Once the app_ru.arb file exists, you can review and refine it by submitting a PR against the file at lib/l10n/app_ru.arb. Every string is a simple key-value pair in JSON, so you don't need to touch any Dart code - just edit the translation values and open a PR. We'll have a CONTRIBUTING_TRANSLATIONS.md guide with the full workflow.

If PRs aren't your preferred workflow, you could also just open an issue with the corrected strings and we'll update the file. Whatever works best for you.

We'll ping this issue when the infrastructure is ready and the first-draft app_ru.arb is available for review.

I am a technical specialist (you can check my profile), so there is no need to explain the translation process.
You can save LLM resources by not translating into Russian: I will still use app_en.arb as the source: the Russian language is too rich in synonyms to trust machine translation for technical terms :)
(For example, we have 3-4 equal translations for the word "node," and agreeing on which one to choose was a real problem within the local community 😄). If you are a native English speaker, you can imagine it as color vs. colour discuss

[gotnull]

I am a technical specialist (you can check my profile), so there is no need to explain the translation process.
You can save LLM resources by not translating into Russian: I will still use app_en.arb as the source: the Russian language is too rich in synonyms to trust machine translation for technical terms :)
(For example, we have 3-4 equal translations for the word "node," and agreeing on which one to choose was a real problem within the local community)

Fair point! The "node" example is a perfect illustration of why we shouldn't let an LLM pick between synonyms that carry real community weight. 😜

We'll ship app_en.arb as the base, you take it from there for Russian. No LLM intermediate step. We'll ping this issue when the i18n infrastructure lands and the English ARB file is ready for you to work from.

Again, thanks for volunteering this. Having a native speaker who already went through the Meshtastic iOS translation process is exactly what we need.

[skrashevich]

I see that you started implementing the translation 👍
Add svk[at]svk.su to Apple TestFlight when you build a test release.

[gotnull]

I see that you started implementing the translation 👍
Add svk[at]svk.su to Apple TestFlight when you build a test release.

I've been working through the internationalization effort this evening and it's honestly a massive job. There are far more hardcoded strings scattered across the UI than expected, so it's been a pretty monumental sweep through the codebase.

That said, I'm steadily extracting everything into proper localization files and wiring it up correctly. The goal is to make future language additions much easier and keep the architecture clean and scalable going forward.

Making solid progress and pushing through it 👍

[skrashevich]

Are you aware that there's something odd going on with your i18n (l10n) key creation process?
I ran a simple script:

import subprocess, json, sys, os, re
from pathlib import Path

PROJECT = Path('/Users/svk/Documents/Projects.nosync/socialmesh')
ARB = PROJECT / 'lib/l10n/app_en.arb'

# 1. Load all keys
with open(ARB) as f:
    data = json.load(f)
keys = [k for k in data.keys() if not k.startswith('@') and k != '@@locale']
print(f'Total keys: {len(keys)}', flush=True)

# 2. Collect all dart source code (excluding generated)
dart_files = [
    p for p in PROJECT.rglob('*.dart')
    if '.dart_tool' not in str(p)
    and 'app_localizations' not in p.name
    and '/.dart/' not in str(p)
]
print(f'Dart files to scan: {len(dart_files)}', flush=True)

# 3. Read all source into one big blob for fast substring search
print('Reading dart files...', flush=True)
all_source = []
for f in dart_files:
    try:
        all_source.append(f.read_text(errors='ignore'))
    except Exception:
        pass
combined = '\n'.join(all_source)

# 4. For each key, check multiple patterns:
#    a) direct: l10n.KEY or .KEY( (method call)
#    b) partial dynamic: prefix of key appears in string interpolation context
#    c) raw string literal: 'KEY' or "KEY" anywhere

unused = []
dynamic_risk = []  # keys that might be dynamic

print('Checking keys...', flush=True)
for i, key in enumerate(keys):
    if i % 1000 == 0:
        print(f'  {i}/{len(keys)}...', flush=True)

    # Direct usage patterns
    found = (
        f'.{key}' in combined or     # l10n.keyName or context.l10n.keyName
        f'l10n.{key}' in combined    # explicit prefix
    )

    if not found:
        # Check if key appears as a raw string (dynamic construction risk)
        in_string = (f"'{key}'" in combined or f'"{key}"' in combined)
        if in_string:
            dynamic_risk.append(key)
        else:
            unused.append(key)

print(f'\n=== RESULTS ===')
print(f'Confirmed unused (no .keyName, no string literal): {len(unused)}')
print(f'Possible dynamic usage (found as string literal):  {len(dynamic_risk)}')
print(f'Used:                                               {len(keys) - len(unused) - len(dynamic_risk)}')

# Group unused by prefix
from collections import defaultdict
groups = defaultdict(list)
for k in unused:
    # extract prefix = first camelCase word
    prefix = re.match(r'^[a-z]+', k)
    prefix = prefix.group() if prefix else 'other'
    groups[prefix].append(k)

print('\n--- Unused by prefix ---')
for prefix, ks in sorted(groups.items(), key=lambda x: -len(x[1])):
    print(f'  {prefix}: {len(ks)}')

# Save full lists
with open('/tmp/unused_keys.txt', 'w') as f:
    f.write('\n'.join(unused))
with open('/tmp/dynamic_risk_keys.txt', 'w') as f:
    f.write('\n'.join(dynamic_risk))

print('\nSaved to /tmp/unused_keys.txt and /tmp/dynamic_risk_keys.txt')

and it showed that about 10% of the strings in the localization file are unused in the code.

[gotnull]

Yes, I'm aware. Those ~650 "unused" keys are expected - the l10n conversion is a multi-sprint effort that's actively in progress.

The workflow is:

1. Create ARB keys for all user-facing strings in a feature area
2. Wire each consumer site to use context.l10n.keyName instead of the hardcoded English
3. Verify with lint + analyzer

Step 1 runs ahead of step 2 by design - it's easier to bulk-create keys for an entire feature module, then systematically wire each screen. We're currently at 9065 keys with about 650 not yet wired to their consumer sites. Those will get consumed as I work through the remaining screens (widget builder editor, telemetry, onboarding, auth, etc.).

It's not a bug in the key creation process - it's just a work-in-progress.

[gotnull]

Alright, the i18n infrastructure is done and everything is wired up. Here's where things stand:

The extraction is complete. All 8,675 user-facing strings are in app_en.arb and every consumer site is wired to context.l10n. The lint checker flags new hardcoded strings so nothing slips back in.

app_ru.arb is ready for you. It has all 8,675 keys — right now they're just English placeholders (no LLM translation, as we discussed). You can grab the file at lib/l10n/app_ru.arb, translate what you want, and open a PR. The English fallback means you can do it at whatever pace works — partially translated strings just show English for the keys you haven't gotten to yet.

Translation guide is up. docs/TRANSLATION_GUIDE.md covers the ARB format, key naming conventions, how to handle parameterized strings and ICU plurals, priority order for which strings to tackle first, and how to test locally. Should have everything you need, but let me know if anything's unclear.

CI validation. There's a GitHub Actions workflow (check-translations.yml) that runs on any PR touching lib/l10n/. It validates that all ARB files parse correctly, checks key consistency against the English template, and verifies that parameterized placeholders like {count} or {name} aren't accidentally dropped in translations. So you'll get immediate feedback if anything's off in a PR.

A few things worth knowing:

• ~914 keys have parameters (stuff like {count}, {name}, {percentage}) — those need to stay in the translated string
• ~121 keys use ICU plural/select syntax — the guide covers how those work
• Keys are prefixed by feature area (channel, message, node, settings, etc.) so you can work through one section at a time

Re: TestFlight — I've added svk[at]svk.su. Will let you know when the next build goes out.

Thanks again for volunteering this. Looking forward to seeing the Russian translation take shape.

[skrashevich]

Alright, the i18n infrastructure is done and everything is wired up. Here's where things stand:

UNUSED L10N KEYS: 91 of 8675

  [nodedex] (28)
    nodedexEvidenceActiveLastHour
    nodedexEvidenceAirtimeTx
    nodedexEvidenceChannelUtilization
    nodedexEvidenceCoSeenWith
    nodedexEvidenceDistinctPositions
    nodedexEvidenceEncounterRate
    nodedexEvidenceEncounterRateLow
    nodedexEvidenceEncountersReliable
    nodedexEvidenceFewEncountersOverDays
    nodedexEvidenceFixedLocation
    nodedexEvidenceFixedPosition
    nodedexEvidenceHighEncounterCount
    nodedexEvidenceInsufficientData
    nodedexEvidenceIrregularTiming
    nodedexEvidenceKnownForDays
    nodedexEvidenceLastSeenDaysAgo
    nodedexEvidenceMaxRange
    nodedexEvidenceMessagesExchanged
    nodedexEvidenceMessagesPerEncounter
    nodedexEvidenceMobileWithMessaging
    nodedexEvidenceModerateEncounterRate
    nodedexEvidencePersistentPresence
    nodedexEvidencePositionsObserved
    nodedexEvidenceRoleIs
    nodedexEvidenceSeenAcrossRegions
    nodedexEvidenceSomewhatIrregularTiming
    nodedexEvidenceTotalEncounters
    nodedexEvidenceUptime
  [task] (11)
    taskErrorCompleteTaskDenied
    taskErrorCompletionNoteRequired
    taskErrorCreateDenied
    taskErrorFailureReasonRequired
    taskErrorInvalidTransition
    taskErrorOnlyAssigneeCanAcknowledge
    taskErrorOnlyAssigneeCanReportFailure
    taskErrorOnlyAssigneeCanStartWork
    taskErrorReassignmentRequiresAssignee
    taskErrorRequiresSupervisorOrAdmin
    taskErrorTerminalState
  [signal] (9)
    signalAcquiringDeviceLocation
    signalAddLocation
    signalConnectToAddLocation
    signalMeshOnlyDebugBanner
    signalNoDeviceConnectedTooltip
    signalOfflineCloudUnavailable
    signalRemoveLocation
    signalRetrievingDeviceLocation
    signalSignInForCloudFeatures
  [settings] (8)
    settingsRemoteAdminConnectedDevice
    settingsTileChannelMessagesSubtitle
    settingsTileClearMessageHistorySubtitle
    settingsTileClearMessageHistoryTitle
    settingsTileDirectMessagesSubtitle
    settingsTileMessageHistorySubtitle
    settingsTileMyBugReportsNotSignedIn
    settingsGlyphMatrixTestSubtitle
  [widget] (7)
    widgetBuilderBoolNo
    widgetBuilderBoolYes
    widgetBuilderMarketplaceAlreadyInstalled
    widgetBuilderMarketplaceFavoritesWithCount
    widgetBuilderMarketplaceInstallWidget
    widgetBuilderMarketplaceLoadingPreview
    widgetBuilderMarketplaceNoWidgetsInCategory
  [incident] (5)
    incidentStateMachineAssigneeRequired
    incidentStateMachineCreateDenied
    incidentStateMachineInvalidTransition
    incidentStateMachinePermissionDenied
    incidentStateMachineTerminalState
  [scanner] (5)
    scannerAutoReconnectDisabledSubtitle
    scannerAutoReconnectDisabledSubtitleWithDevice
    scannerEnableAutoReconnectMessage
    scannerEnableAutoReconnectMessageWithDevice
    scannerEnableAutoReconnectTitle
  [firmware] (3)
    firmwareUpdateAvailable
    firmwareUpdateLatestVersion
    firmwareUpdateUpToDate
  [auth] (3)
    authErrorNoUserSignedIn
    authErrorSessionLost
    authErrorVerificationCodeFailed
  [admin] (2)
    adminProductsVendorUnverifiedSubtitle
    adminConformanceBundleTitle
  [connection] (2)
    connectionErrorDeviceNotFound
    connectionErrorDeviceReset
  [profile] (1)
    profileCallsignInappropriate
  [telemetry] (1)
    telemetryEnvironmentLegendTemperature
  [device] (1)
    devicePrivacyUpdateFrequencyDescription
  [position] (1)
    positionConfigGpsUpdateIntervalSubtitle
  [power] (1)
    powerConfigAdcMultiplierOverrideSubtitle
  [mesh] (1)
    meshHealthRssiDegraded
  [offline] (1)
    offlineQueueMaxRetries
  [deep] (1)
    deepLinkUnableToOpenLink

[gotnull]

Good catch running the audit, but those 91 keys are all wired. Could be that your clone is behind or the script you're using is wrong. The wiring commits landed between Mar 2–4 (3accc622 through c9eadead), all pushed well before your comment. A git pull should clear it up.

Quick breakdown of where they live:

• nodedex (28): lib/features/nodedex/services/trait_engine.dart
• task (11): lib/features/tasks/services/task_state_machine.dart
• signal (9): lib/features/signals/screens/create_signal_screen.dart
• settings (8): lib/features/settings/settings_screen.dart
• widget (7): lib/features/widget_builder/ (data_binding + marketplace screen)
• incident (5): lib/features/incidents/services/incident_state_machine.dart
• scanner (5): lib/features/scanner/scanner_screen.dart
• Remaining singletons spread across auth_providers, connection_providers, firmware_update_screen, profile_screen, etc.

After pulling you can verify with:

python3 -c "
import json, pathlib
arb = json.load(open('lib/l10n/app_en.arb'))
keys = [k for k in arb if not k.startswith('@') and k != '@@locale']
src = ''.join(p.read_text(errors='ignore') for p in pathlib.Path('lib').rglob('*.dart')
             if '/generated/' not in str(p) and 'app_localizations' not in p.name)
unused = [k for k in keys if f'.{k}' not in src]
print(f'Total: {len(keys)}, Unused: {len(unused)}')
for k in unused: print(f'  {k}')
"

Should show 8675/0. Let me know if anything still looks off after pulling.

[skrashevich]

I’m sorry, my fuckup: I didn’t account for some syntax nuances of Dart in the script.

Almost 9,000 lines — that’s unexpectedly solid :) In the near future (today or tomorrow) i'll submit a PR with a translation using an LLM (opus-4.6, I think), based on the current translation of the official application, and a quick manual proofreading.
Then, after some time, we’ll do a full manual proofreading and editing with the help of the community.

[gotnull]

No worries - Dart's multi-line chaining makes simple substring matching trickier than it looks. 9k keys is what happens when you point an LLM at 900 files and tell it to extract everything that moves :/

Re: the Russian translation, I can kick off an Opus 4.6 pass on app_ru.arb from my end using the annotated English file as source. That way you get a complete first draft to proofread rather than having to generate it yourself. You'd just focus on the review pass: fixing the terminology choices (the "node" synonym problem you mentioned), adjusting tone, and catching anything the model gets wrong with mesh-specific vocabulary.