meshcore-hub/docs/i18n.md

Translation Reference Guide

This document provides a comprehensive reference for translating the MeshCore Hub web dashboard.

File Structure

Translation files are JSON files named by language code (e.g., en.json, es.json, fr.json) and located in /src/meshcore_hub/web/static/locales/.

Variable Interpolation

Many translations use {{variable}} syntax for dynamic content. These must be preserved exactly:

"total": "{{count}} total"

When translating, keep the variable names unchanged:

"total": "{{count}} au total"  // French example

Translation Sections

1. entities

Core entity names used throughout the application. These are referenced by other translations for composition.

Key	English	Context
home	Home	Homepage/breadcrumb navigation
dashboard	Dashboard	Main dashboard page
nodes	Nodes	Mesh network nodes (plural)
node	Node	Single mesh network node
node_detail	Node Detail	Node details page
advertisements	Adverts	Network advertisements (plural, used in nav menus and hero cards)
advertisement	Advert	Single advertisement
messages	Messages	Network messages (plural)
message	Message	Single message
map	Map	Network map page
members	Members	Network members (plural)
member	Member	Single network member
tags	Tags	Node metadata tags (plural)
tag	Tag	Single tag
channel	Channel	Mesh network channel

Usage: These are used with composite patterns. For example, t('common.add_entity', { entity: t('entities.node') }) produces "Add Node".

2. common

Reusable patterns and UI elements used across multiple pages.

Actions

Key	English	Context
filter	Filter	Filter button/action
clear	Clear	Clear action
clear_filters	Clear Filters	Reset all filters
search	Search	Search button/action
cancel	Cancel	Cancel button in dialogs
delete	Delete	Delete button
edit	Edit	Edit button
move	Move	Move button
save	Save	Save button
save_changes	Save Changes	Save changes button
add	Add	Add button
close	close	Close button (lowercase for accessibility)
sign_in	Sign In	Authentication sign in
sign_out	Sign Out	Authentication sign out
go_home	Go Home	Return to homepage button

Composite Patterns with Entity

These patterns use {{entity}} variable - the entity name is provided dynamically:

Key	English	Example Output
add_entity	Add {{entity}}	"Add Node", "Add Tag"
add_new_entity	Add New {{entity}}	"Add New Member"
edit_entity	Edit {{entity}}	"Edit Tag"
delete_entity	Delete {{entity}}	"Delete Member"
delete_all_entity	Delete All {{entity}}	"Delete All Tags"
move_entity	Move {{entity}}	"Move Tag"
move_entity_to_another_node	Move {{entity}} to Another Node	"Move Tag to Another Node"
copy_entity	Copy {{entity}}	"Copy Tags"
copy_all_entity_to_another_node	Copy All {{entity}} to Another Node	"Copy All Tags to Another Node"
view_entity	View {{entity}}	"View Node"
recent_entity	Recent {{entity}}	"Recent Advertisements"
total_entity	Total {{entity}}	"Total Nodes"
all_entity	All {{entity}}	"All Messages"

Empty State Patterns

These patterns indicate when data is absent. Use {{entity}} in lowercase (e.g., "nodes", not "Nodes"):

Key	English	Context
no_entity_found	No {{entity}} found	Search/filter returned no results
no_entity_recorded	No {{entity}} recorded	No historical records exist
no_entity_defined	No {{entity}} defined	No configuration/definitions exist
no_entity_in_database	No {{entity}} in database	Database is empty
no_entity_configured	No {{entity}} configured	System not configured
no_entity_yet	No {{entity}} yet	Empty state, expecting data later
entity_not_found_details	{{entity}} not found: {{details}}	Specific item not found with details
page_not_found	Page not found	404 error message

Confirmation Patterns

Used in delete/move dialogs. Variables: {{entity}}, {{name}}, {{count}}:

Key	English	Context
delete_entity_confirm	Are you sure you want to delete {{entity}} {{name}}?	Single item delete confirmation
delete_all_entity_confirm	Are you sure you want to delete all {{count}} {{entity}} from {{name}}?	Bulk delete confirmation
cannot_be_undone	This action cannot be undone.	Warning in delete dialogs

Success Messages

Toast/flash messages after successful operations:

Key	English	Context
entity_added_success	{{entity}} added successfully	After creating new item
entity_updated_success	{{entity}} updated successfully	After updating item
entity_deleted_success	{{entity}} deleted successfully	After deleting item
entity_moved_success	{{entity}} moved successfully	After moving tag to another node
all_entity_deleted_success	All {{entity}} deleted successfully	After bulk delete
copy_all_entity_description	Copy all {{count}} {{entity}} from {{name}} to another node.	Copy operation description

Navigation & Status

Key	English	Context
previous	Previous	Pagination previous
next	Next	Pagination next
loading	Loading...	Loading indicator
error	Error	Error state
failed_to_load_page	Failed to load page	Page load error

Counts & Metrics

Key	English	Context
total	{{count}} total	Total count display
shown	{{count}} shown	Filtered count display
count_entity	{{count}} {{entity}}	Generic count with entity

Form Fields & Labels

Key	English	Context
type	Type	Type field/column header
name	Name	Name field/column header
key	Key	Key field (for tags)
value	Value	Value field (for tags)
time	Time	Time column header
actions	Actions	Actions column header
updated	Updated	Last updated timestamp
view_details	View Details	View details link
all_types	All Types	"All types" filter option
all_channels	All Channels	"All channels" filter option
all_members	All Members	"All members" filter option (only shown when OIDC is enabled)
all_operators	All Operators	"All operators" filter option for operator-only filter dropdowns
filter_member_label	Member	Label for member filter dropdown
filter_operator_label	Operator	Label for operator filter dropdown (used on Nodes, Advertisements, Map pages)
node_type	Node Type	Node type field
show	Show	Show/display action
search_placeholder	Search by name, ID, or public key...	Search input placeholder
contact	Contact	Contact information field
description	Description	Description field
callsign	Callsign	Amateur radio callsign field
tags	Tags	Tags label/header
last_seen	Last Seen	Last seen timestamp (table header)
first_seen_label	First seen:	First seen label (inline with colon)
last_seen_label	Last seen:	Last seen label (inline with colon)
location	Location	Geographic location
public_key	Public Key	Node public key
received	Received	Received timestamp
received_by	Received By	Received by field
receivers	Receivers	Multiple receivers
from	From	Message sender
hops	Hops	Number of mesh hops (table header)
observers	Observers	Observers of an event
snr_db	SNR (dB)	Signal-to-noise ratio in decibels (table header)
unnamed	Unnamed	Fallback for unnamed items
unnamed_node	Unnamed Node	Fallback for unnamed nodes
sort_by	Sort by	Label before mobile sort dropdown

Note: Keys ending in _label have colons and are used inline. Keys without _label are for table headers.

3. links

Platform and external link labels:

Key	English	Context
website	Website	Website link label
github	GitHub	GitHub link label (preserve capitalization)
discord	Discord	Discord link label
youtube	YouTube	YouTube link label (preserve capitalization)
profile	Profile	Radio profile label

4. auto_refresh

Auto-refresh controls for list pages (nodes, advertisements, messages):

Key	English	Context
pause	Pause auto-refresh	Tooltip on pause button when auto-refresh is active
resume	Resume auto-refresh	Tooltip on play button when auto-refresh is paused

5. time

Time-related labels and formats:

Key	English	Context
days_ago	{{count}}d ago	Days ago (abbreviated)
hours_ago	{{count}}h ago	Hours ago (abbreviated)
minutes_ago	{{count}}m ago	Minutes ago (abbreviated)
less_than_minute	<1m ago	Less than one minute ago
last_7_days	Last 7 days	Last 7 days label
per_day_last_7_days	Per day (last 7 days)	Per day over last 7 days
over_time_last_7_days	Over time (last 7 days)	Over time last 7 days
activity_per_day_last_7_days	Activity per day (last 7 days)	Activity chart label

6. node_types

Mesh network node type labels:

Key	English	Context
chat	Chat	Chat node type
repeater	Repeater	Repeater/relay node type
companion	Companion	Companion/observer node type
room	Room Server	Room server/group node type
unknown	Unknown	Unknown node type fallback

7. home

Homepage-specific content:

Key	English	Context
welcome_default	Welcome to the {{network_name}} mesh network dashboard. Monitor network activity, view connected nodes, and explore message history.	Default welcome message
all_discovered_nodes	All discovered nodes	Stat description
network_info	Network Info	Network info card title
network_activity	Network Activity	Activity chart title
frequency	Frequency	Radio frequency label
bandwidth	Bandwidth	Radio bandwidth label
spreading_factor	Spreading Factor	LoRa spreading factor label
coding_rate	Coding Rate	LoRa coding rate label
tx_power	TX Power	Transmit power label
advertisements	Adverts	Homepage stat label
messages	Messages	Homepage stat label

Note: MeshCore tagline "Off-Grid, Open-Source Encrypted Messaging" is hardcoded in English and should not be translated (trademark).

8. dashboard

Dashboard page content:

Key	English	Context
all_discovered_nodes	All discovered nodes	Stat label
recent_channel_messages	Recent Channel Messages	Recent messages card title
channel	Channel {{number}}	Channel label with number

9. nodes

Node detail page labels:

Key	English	Context
scan_to_add	Scan to add as contact	QR code instruction
ownership	Ownership	Adoption card heading on node detail page
adopt	Adopt	Adopt button (operator/admin only)
release	Release	Release button (owner or admin only)
adopted_by	Adopted by {{name}}	Display name of adopting user ({{name}} = user name or ID)
not_adopted	This node has not been adopted by any operator.	Shown when node is unadopted and user is operator/admin
adopt_success	Node adopted successfully	Flash message after adopting
release_success	Node released successfully	Flash message after releasing
release_confirm	Are you sure you want to release this node?	Confirmation dialog for release

Sort Options (nodes.sort)

Mobile sort dropdown labels for the nodes list page:

Key	English	Context
sort.last_seen_newest	Last Seen (newest)	Default sort: most recently seen first
sort.last_seen_oldest	Last Seen (oldest)	Least recently seen first
sort.name_az	Name (A–Z)	Alphabetical by display name
sort.name_za	Name (Z–A)	Reverse alphabetical by display name
sort.key_asc	Public Key (ascending)	Sorted by public key ascending
sort.key_desc	Public Key (descending)	Sorted by public key descending

10. advertisements

Route type filter and sort options for the advertisements list page:

Route Type Filter

Key	English	Context
filter_route_type_label	Advert Type	Label for route type filter dropdown
route_type_all	All	Show all route types (no filter)
route_type_flood	Flood & Relay	Show flood and transport_flood adverts (default)
route_type_direct	Zero-hop only	Show only direct (zero-hop) adverts
route_type_unknown	Unknown	Displayed when route_type is NULL (historical records)
col_route_type	Type	Table column header for route type

Sort Options (advertisements.sort)

Mobile sort dropdown labels for the advertisements list page:

Key	English	Context
sort.newest	Time (newest)	Default sort: most recent first
sort.oldest	Time (oldest)	Oldest first
sort.node_az	Node (A–Z)	Alphabetical by node display name
sort.node_za	Node (Z–A)	Reverse alphabetical by node display name
sort.key_asc	Public Key (ascending)	Sorted by public key ascending
sort.key_desc	Public Key (descending)	Sorted by public key descending

11. messages

Message type labels:

Key	English	Context
type_direct	Direct	Direct message type
type_channel	Channel	Channel message type
type_contact	Contact	Contact message type
type_public	Public	Public message type

Sort Options (messages.sort)

Mobile sort dropdown labels for the messages list page:

Key	English	Context
sort.newest	Time (newest)	Default sort: most recent first
sort.oldest	Time (oldest)	Oldest first
sort.type_az	Type (A–Z)	Alphabetical by message type
sort.type_za	Type (Z–A)	Reverse alphabetical by message type
sort.from_az	From (A–Z)	Alphabetical by sender name
sort.from_za	From (Z–A)	Reverse alphabetical by sender name
sort.message_az	Message (A–Z)	Alphabetical by message text
sort.message_za	Message (Z–A)	Reverse alphabetical by message text

12. map

Map page content:

Key	English	Context
show_labels	Show Labels	Toggle to show node labels
infrastructure_only	Infrastructure Only	Toggle to show only infrastructure nodes (OIDC required, only rendered when OIDC_ENABLED=true; data sourced from node adoption, not tags)
legend	Legend:	Map legend header (only rendered when OIDC_ENABLED=true)
infrastructure	Infrastructure	Infrastructure node category (only rendered when OIDC_ENABLED=true; based on adoption status)
public	Public	Public node category
nodes_on_map	{{count}} nodes on map	Status text with coordinates
nodes_none_have_coordinates	{{count}} nodes (none have coordinates)	Status text without coordinates
gps_description	Nodes are placed on the map based on GPS coordinates from node reports or manual tags.	Map data source explanation
owner	Owner:	Node owner label
role	Role:	Member role label
select_destination_node	-- Select destination node --	Dropdown placeholder

13. members

Members page content:

Key	English	Context
empty_state_description	No members yet.	Empty state heading
empty_description	Members will appear here once users log in and adopt nodes.	Empty state description

14. channels

Channel management and filter UI:

Key	English	Context
title	Channels	Page title
add_channel	Add Channel	Add button label
edit_channel	Edit Channel	Edit modal title
delete_channel	Delete Channel	Delete modal title
delete_confirm	Are you sure you want to delete channel {{name}}?	Delete confirmation message
name_label	Channel Name	Form label
key_label	Channel Key (hex)	Form label
visibility_label	Visibility	Form label
visibility_community	Community	Community visibility section heading
visibility_member	Member	Member visibility section heading
visibility_operator	Operator	Operator visibility section heading
visibility_admin	Admin	Admin visibility section heading
enabled_label	Enabled	Form label
channel_hash_label	Hash	Column header
disabled	Disabled	Disabled channel badge
optgroup_standard	Standard	Optgroup label for built-in channels (Public, Test) in channel filter dropdown
optgroup_custom	Custom	Optgroup label for user-defined channels in channel filter dropdown

15. not_found

404 page content:

Key	English	Context
description	The page you're looking for doesn't exist or has been moved.	404 description

16. custom_page

Custom markdown page errors:

Key	English	Context
failed_to_load	Failed to load page	Page load error

17. auth

Authentication UI:

Key	English	Context
login	Login	Login button text
logout	Logout	Logout menu item
login_required	Login required	Login required heading
admin_required	Admin access required	Admin access denied message
login_hint	Log in to access admin features	Hint shown to non-admin users
logged_in_as	Logged in as {{name}}	Logged in status ({{name}} = user display name)
session_expired	Session expired, please log in again	Session expiry notice
role_admin	admin	Admin role badge text
role_member	member	Member role badge text

18. footer

Footer content:

Key	English	Context
powered_by	Powered by	"Powered by" attribution

19. user_profile

User profile page (OIDC authenticated users):

Key	English	Context
title	Profile	Page heading
your_profile	Your Profile	Profile card heading
profile_updated	Profile updated successfully	Flash message after save
save_profile	Save Profile	Save button label
name_label	Display Name	Form label
name_placeholder	Your name or preferred name	Input placeholder
callsign_label	Callsign	Form label
callsign_placeholder	Amateur radio callsign (e.g., W1ABC)	Input placeholder
description_label	Description	Form label
description_placeholder	A short bio or description	Input placeholder
url_label	Website / Profile Link	Form label
url_placeholder	https://...	Input placeholder
adopted_nodes	Adopted Nodes	Adopted nodes card heading
no_adopted_nodes	No adopted nodes	Empty state
login_to_view	Log in to view your profile	Unauthenticated notice

Translation Tips

1. Preserve HTML tags: Some strings contain <code>, <strong>, or <br/> tags - keep these intact.

2. Preserve variables: Keep {{variable}} placeholders exactly as-is, only translate surrounding text.

3. Entity composition: Many translations reference entities.* keys. When translating entities, consider how they'll work in composite patterns (e.g., "Add {{entity}}" should make sense with "Node", "Tag", etc.).

4. Capitalization:

   • Entity names should follow your language's capitalization rules for UI elements
   • Inline labels (with colons) typically use sentence case
   • Table headers typically use title case
   • Action buttons can vary by language convention

5. Colons: Keys ending in _label include colons in English. Adjust punctuation to match your language's conventions for inline labels.

6. Plurals: Some languages have complex plural rules. You may need to add plural variants for {{count}} patterns. Consult the i18n library documentation for plural support.

7. Length: UI space is limited. Try to keep translations concise, especially for button labels and table headers.

8. Brand names: Preserve "MeshCore", "GitHub", "YouTube" capitalization.

Testing Your Translation

1. Create your translation file: locales/xx.json (where xx is your language code)
2. Copy the structure from en.json
3. Translate all values, preserving all variables and HTML
4. Test in the application by setting the language
5. Check all pages for:
   • Text overflow/truncation
   • Proper variable interpolation
   • Natural phrasing in context

Getting Help

If you're unsure about the context of a translation key, check:

1. The "Context" column in this reference
2. The JavaScript files in /src/meshcore_hub/web/static/js/spa/pages/
3. Grep for the key: grep -r "t('section.key')" src/