Add internationalization and Persian (fa) language support

[sajjadrashidi]

Summary

Request to implement internationalization (i18n) for the Freight-Fate project and add Persian (fa) as a supported language.

Goals

• Prepare the application to support multiple languages
• Add full UI translations for Persian
• Support right-to-left (RTL) layout for proper rendering of RTL languages like Persian

Why this change matters

• Enables Persian-speaking users to use the app more effectively and opens the product to a new market and user base.
• Prepares the codebase for adding more languages in the future and increases flexibility and maintainability.

Proposed implementation (recommended tasks)

1. i18n foundation

   • Select and integrate a suitable i18n library (e.g., i18next or similar) and configure basics.
   • Move all user-facing text into separate resource files under /locales/{lang}/.

2. Add Persian (fa)

   • Create locales/fa/ directory with translation files (JSON or project-specific format) for all UI keys.
   • Review and refine translations for consistency and naturalness.

3. RTL support

   • Identify parts of CSS/layout that require RTL adjustments.
   • Implement necessary changes (e.g., using logical CSS properties, direction: rtl) and test key pages.

4. Date/number/units formatting

   • Ensure locale-specific formatting for dates, times, numbers, and units.
   • Use the Intl API or a suitable library for locale-aware formatting.

5. Fonts and typography

   • Evaluate and include web fonts with good Persian glyph coverage if needed.
   • Ensure proper kerning and readability across sizes.

6. Testing and quality

   • Add unit/integration tests to verify presence of translation keys and fallback behavior.
   • Add manual test cases for critical pages in Persian and RTL layout checks.

7. Documentation

   • Add a CONTRIBUTING or README section explaining how to add new translations and naming conventions for keys.

Acceptance criteria

• Users can select Persian from settings and the entire UI renders in Persian.
• All core pages render correctly without layout breakage in RTL mode.
• No hard-coded user-facing strings remain; all strings are sourced from translation files.
• Tests for translations and RTL behavior are added and run in CI.

Initial time estimates

• Research and select i18n approach: 1-2 days
• Core implementation and initial translation files: 3-5 days
• CSS/RTL adjustments and testing: 2-4 days
• Documentation and feedback: 1-2 days

Additional notes

• If the repository already contains any templates or translation files, they should be reviewed and consolidated.
• Suggested labels: i18n, localization, enhancement, fa
• Suggested assignee: Orinks

Please create this as an issue labeled "enhancement" and assign it to the Orinks team.

[day-garwood]

I think there is a larger architectural question here that is worth considering, especially in light of #21 and the possibility of supporting multiple countries in future.

The difficulty is that not all user-facing words fall neatly into either "translatable UI text" or "fixed game data". There is a fairly large middle ground where terminology is both linguistic and country-specific.

Some things are straightforward. For example, "Continue latest career", "Settings", "Fuel remaining", etc. are clearly interface strings and should be translated according to the player's selected language.

Likewise, some things clearly belong to the simulated country rather than the interface language: currency, haulage laws, traffic side, road network definitions, weight limits, facility types, and so on.

The awkward part is deciding what happens to the language used to describe those country-specific concepts.

For example, are words such as "truck", "lorry", "dock", and "loading bay" ordinary translatable strings?

If they are, an English-speaking US driver using a British English translation could end up driving a lorry towards a loading bay in Texas, while a British driver using a US English translation might be driving a truck towards the dock in Birmingham. Neither is technically incomprehensible, but both would feel very strange because those words are partly regional terminology rather than simply different translations of the same UI label.

Should a German player driving the UK expect to pay in "pounds", "Pfunde", or "Euros"?

Road terminology is even more problematic.

An English-speaking player driving in Germany would probably expect to hear "Autobahn", not necessarily the translated equivalent "motorway". On the other hand, if "Autobahn" is simply represented by a generic road type whose display name is translated according to locale, a US English translation might conceivably turn British motorways into "interstates", which would be both inaccurate and fairly amusing.

"Interstate" itself is a good example of the problem. In the context of roads, it refers to a specific US highway system. Translating the word literally into another language would not necessarily make sense, because the concept itself belongs to the US rather than being a generic synonym for "major road".

I think this suggests that the simulation should ideally store concepts rather than English words.

The country profile would define what each concept means mechanically, while a separate presentation/localisation layer would decide how that concept is described to the player.

That still leaves another policy decision: how much local terminology should be preserved when the player's interface language differs from the country being driven in?

For example, an English-speaking player in Germany could plausibly hear:

"Continue on the Autobahn for 20 kilometres."

The surrounding sentence is translated into the player's language, but the country-specific term "Autobahn" is preserved because it is part of the environment being simulated.

Placenames introduce the same issue from another direction. The underlying place should obviously belong to world data, but its displayed name may still vary by language.

Germany / Deutschland is the obvious example, as is Munich / München.

It may therefore make sense for places to have a stable internal identity with one or more display names, rather than treating the English placename as the data itself.

That could also allow the player to choose between translated and native placenames independently of the UI language, for example:

UI language: English (UK)
Placenames: Native
World terminology: Native/local
Units: Country default

A player driving in Germany could then hear something like:

"Take the A8 towards München. Continue on the Autobahn for 12 kilometres."

This preserves the sense of actually being in Germany without requiring the player to understand German UI text.

I would be wary of tying language directly to country profiles, because country and language are not equivalent concepts. The UK alone makes that obvious once Wales is considered, and countries such as Belgium, Switzerland, and Canada make it even more complicated.

If crossing a country or regional boundary automatically changed the game's language, a player could have the rather entertaining experience of crossing from England into Wales and suddenly wondering why the entire game had started speaking Welsh.

I think the cleanest separation would therefore be something like:

• The simulated jurisdiction determines laws, currency, infrastructure, road rules, etc.
• The player's locale determines interface language and general linguistic conventions.
• The simulated country or region determines native/local terminology and names.
• A presentation policy determines whether those local terms are preserved or translated.

If internationalisation is tackled without deciding where those boundaries lie first, it may become much harder to add other countries cleanly later.