feat(i18n): add Persian/Farsi and Iran support

[khaira777]

Context

Discussion: https://github.com/orgs/FreeOpenSourcePOS/discussions/239

A community member requested Persian/Farsi support and suggested adding Iran to the country profile. This issue tracks the work without treating a country entry as complete language support.

Goal

Provide a reliable first-class experience for Iranian businesses using Persian (fa-IR) and the Iran (IR) country profile.

Current Implementation Status

Persian is recognized internally, but it is intentionally not selectable by normal users yet. dir="rtl" support currently provides semantic document direction only; it does not mean all visual RTL layout work is complete.

#241 is an umbrella issue. Follow-up PRs must use Refs #241 only and must not close this issue until all acceptance criteria are complete.

Scope

• Add the Iran country profile with verified locale, currency, timezone, and dialing information.
• Add Persian/Farsi as a supported UI language.
• Add a complete Persian translation with the same key coverage as the existing languages.
• Add RTL document and layout support, including setup, dashboard, POS, KDS, and settings.
• Verify Persian date, number, currency, and text rendering.
• Test browser receipts and thermal receipts with Persian text where the printer supports it.
• Confirm the correct Iranian business identifier terminology before choosing the tax registration label. Rial is a currency, not a tax identifier.

Known Native Feedback & Decisions

Confirmed:

• Iranian Economic Code terminology: کد اقتصادی

Awaiting Native Feedback / Decision:

• ﷼ / ریال / تومان
• whether Toman is display-only while storage remains IRR
• Persian vs Latin digits
• Shamsi/Persian vs Gregorian calendar
• whether temporary LTR UI is acceptable
• available thermal printer model
• whether شناسه ملی should be a separate field

Delivery Checklist

Completed

• Iran country profile:

  • IR
  • fa-IR
  • IRR
  • Asia/Tehran
  • +98
  • Economic Code
  • no enforced tax ID format

• Initial fa.json

  • full key parity
  • translation integrity tests

• Internal Persian runtime plumbing

  • canonical Language type recognizes fa
  • Persian translation bundle registered
  • Zustand/auth/Tenant language plumbing
  • server/KDS metadata accepts fa

• Semantic document language/direction plumbing

  • main application fa -> lang="fa-IR" / dir="rtl"
  • standalone KDS equivalent handling

Still pending

• Native translation completion/review

  • 732 out of 1668 values are currently identical to English on current main
  • structural key completeness does NOT equal linguistic completeness

• Persian user-facing enablement

  • Setup selector
  • Settings selector
  • browser auto-detection
  • keep disabled until readiness requirements are met

• Visual RTL verification/fixes

  • setup
  • auth
  • dashboard
  • POS
  • dialogs
  • Settings
  • KDS
  • mixed LTR/RTL fields

• Audit remaining hard-coded EN/ES/PT assumptions

  • include demo-data language handling
  • locale-specific screens such as WhatsApp
  • identify other cases but do NOT fix them in this task

• Iran-specific localized terminology

  • Persian UI should display Economic Code as کد اقتصادی
  • determine whether شناسه ملی needs a separate field
  • do not hardcode Persian into shared country data

• Locale UX decisions

  • Rial vs Toman display
  • storage/display conversion policy
  • Persian vs Latin digits
  • Persian/Shamsi vs Gregorian calendar
  • never silently convert monetary units

• Browser receipt support

  • Persian direction
  • localized receipt labels
  • mixed-direction content
  • date/number/currency behavior
  • font/render verification

• Raw thermal receipt support/fallback

  • ESC/POS encoding
  • Persian glyph support
  • shaping
  • bidi order
  • unsupported-printer fallback
  • physical printer verification

• Final focused tests/documentation

• Final Persian Setup/Settings enablement only after prerequisites pass

Out of scope for the initial language/country contribution

• This issue does not by itself promise official Iranian tax compliance or a complete Iranian tax pack. Tax rules should be added separately after they are verified.
• Payment-provider, fiscal e-invoicing, and other Iran-specific integrations are separate work.

Contribution notes

This is broad enough to be split into smaller pull requests after someone takes ownership. A contributor who can provide or review native Persian translations and local tax terminology would be especially valuable. The initial implementation should avoid shipping a partial translation or an untested RTL layout as if support were complete.

Acceptance criteria

• Persian can be selected during setup and in settings, persists server-side, and is inherited by the standalone KDS.
• The main POS flows do not expose raw translation keys and render correctly in RTL.
• Country selection for Iran supplies the expected locale, currency, timezone, and phone dial code.
• Dates, amounts, and receipts are tested for the chosen Rial/Toman behavior.
• Unsupported printer capabilities fail safely or use a documented fallback.
• Existing English, Spanish, and Portuguese behavior remains unchanged.

[MaMaDTHUG82]

on it

[khaira777]

on it

@MaMaDTHUG82

Thanks for taking this on. Issue #241 covers several areas, so feel free to break the work into smaller focused PRs if that makes sense.

Start with the parts you can handle and verify. If you get stuck on anything or the scope feels too large, comment here and we can help split it up or take on a piece.

[MaMaDTHUG82]

thank you too sir to let me do it , @khaira777

The fact is that Iranians should feel more comfortable in English ( User Friendly ), that's why we work with English in various programs most of the time.
Because Persian has not always been in all games or programs

I translated various parts of the program except for the settings into Persian, because it was really not understandable and even I myself can't figure it out because the meanings are complicated...

I tried if the writing stays LTR, it won't interfere with the menus

I want to run this program in my friend's restaurant, I'll definitely send pictures of it later

And inside Iran, taxes are strange and considering the economy, it doesn't seem to exist at all, businesses with low sales are not taxed and people with high-profit businesses also bypass it, but I'm going to set it in the files

[MaMaDTHUG82]

fa.json
i did the #267 , was terrible

[MaMaDTHUG82]

the dial code looks like india , but instead +91 its +98
and if LTR with this fa.json makes problems that not so emergence we could pass it , its need alot of time to fix it surly , after that we even could add more LTR languages .
need a icon for IRR for currency

[khaira777]

@MaMaDTHUG82 You actually did a lot of useful work here, especially for a first GitHub contribution. The Persian translation itself is a big contribution - #241 just turned out to touch much more technical plumbing than it looks like from the outside.

I’m going to help take over the technical integration from here on this same PR so your contribution and authorship stay attached to it. We’ll split the remaining RTL, KDS, formatting and printer work into smaller follow-ups rather than asking you to solve everything at once.

Your Persian knowledge is the part we need most. Once the technical pieces are wired up, it would be really useful if you could review the wording and eventually test it at your friend’s restaurant like you mentioned.

Thanks for jumping into this - this is exactly how open-source contributions get built through review and collaboration.

[khaira777]

@MaMaDTHUG82 Thanks - your earlier answer about using کد اقتصادی for the Economic Code is clear, so we’ll use that.

A few more Iran-specific UX questions would help us avoid guessing:

For restaurant prices and receipts, what feels most natural: ﷼, ریال, or تومان?
If people usually think in Toman, should FloCafe still store amounts in IRR/Rial and only offer Toman as an optional display?
For prices, quantities and phone numbers, do users normally expect Persian digits like ۱۲۳۴ or Latin digits like 1234?
For dates, would you expect the Persian/Shamsi calendar, Gregorian, or an option for both?
Is keeping the current layout LTR temporarily still usable enough for you while we work on full RTL separately?
If your friend’s restaurant has a thermal printer, could you tell us the printer model? That would help later with real Persian receipt testing.

One more small question: for an Iranian restaurant receipt/settings page, is کد اقتصادی enough as the business identifier, or would شناسه ملی normally also need to appear as a separate field?

No need to research legal rules for us - just tell us what feels normal in real use. We’ll verify tax/compliance separately.