# Bangla and English localization implementation plan Status: implemented in the working tree for Bangla/English interface localization. The original plan below is retained as the implementation reference. Confirmed scope: Bangla (`bn`) is the default. English (`en`) is selectable. This phase translates all application-owned interface text, including system messages and generated report labels. Editable database content remains in its original language. ## Implementation verification (2026-10-15) - Bangla default, encrypted cookie/session persistence, validated locale endpoint, and navbar selectors are implemented for the public site and admin, including guest authentication pages. - Laravel catalogs feed Blade and reactive Vue translations. The application no longer uses the Modular permanent translation cache; catalogs are read directly, so translation edits require no dictionary-cache purge. - Static interface conversion spans public pages/widgets, admin pages/shared controls, validation, system feedback, built-in menu metadata, PDF/Excel labels, and notification templates. Custom database content is preserved. - The additive migration for menu translation keys and captured donation/recurring locales has been applied locally. Apply it through the normal migration process on other environments. - 168 focused PHP tests pass. JavaScript translation tests, the production frontend build, and Vue TypeScript checks pass. Browser checks confirm public switching and admin-login switching with unsaved input preserved. - Real PDF endpoint tests exposed and fixed direct mPDF output: both report controllers now return complete PDF bytes through Laravel responses. - The complete repository suite was also exercised explicitly with module test directories. Remaining failures involve existing ACL fixture counts, missing backup configuration, strict legacy CMS assertions, a homepage test without migrated tables, analytics markup, and the starter test's missing `home` route. They are outside the localization change. ESLint also reports existing unused variables in several application components. - Existing public image URLs returning 403/404 limit visual image checks. A signed-in admin browser walkthrough still requires a valid local account; authenticated server-side module coverage is included in the passing focused suite. ## 1. Project findings The structure review covered application bootstrapping, configuration, routing, providers, module structure, database schema, frontend entry points, layouts, shared components, representative module screens/controllers/requests, notifications, exports, and test configuration. Counts describe source inventory, not the number of files requiring edits. | Area | Current structure and localization implications | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Backend | Laravel 13.35.0; 24 modules under `modules/`; most application behavior lives here rather than `app/`. Module providers register public and admin routes through `Modules\Support\BaseServiceProvider`. | | Admin frontend | Inertia Laravel 3.5.1, Vue 3, Tailwind 4. There are 154 Vue files under `resources/js`, including active `Pages` and starter `pages` directories. Active Blade root loads `resources/js/app.js`. | | Public frontend | Blade layout in `resources-site/views/site-layout.blade.php`, module-owned Blade pages, and nine Vue widgets initialized through `resources-site/js/create-vue-app.js` and `index-app.js`. This frontend does not use Inertia. | | Templates | 15 public Blade templates, 30 module Blade templates, and six templates under `resources/views`. Include email, pagination, menu, and PDF templates in the inventory. | | Routes | `route:list --except-vendor` currently reports 247 routes. Public pages and admin authentication use the `web` group; protected module routes add `auth.user`. | | Existing translations | `resources/js/Plugins/Translations.js` exposes `__()` and provides `translate`; `useTrans.js`, `useTitle.js`, menu components, and some CRUD pages already use it. Preserve these call sites during migration. | | Catalogs | Only `lang/en/pagination.php` and Modular English/Portuguese catalogs/custom validation are present. There is no Bangla catalog. | | Existing loader | `` injects `window._translations` into the admin root. Its package loader caches dictionaries forever in production, merges package JSON after application values, flattens PHP files without their filename prefix, and does not build an English fallback overlay. Replace this integration in application code. | | Admin reactivity | The helper reads a global initial-page dictionary. Inertia shared props currently contain no locale or translations. Changing server locale alone would leave a persistent admin session showing old translations. | | Navigation | Public navbar/mobile drawer live in `resources-site/views/components/header.blade.php`. Admin navbar is `resources/js/Components/Misc/AppTopBar.vue`; menu labels originate in `Configs/menu.js`. Public menus are database-backed and cached by menu slug in `modules/Menu/Services/MenuRenderer.php`. | | Formatting and output | Charts/reports contain fixed `en-US` formatting; controllers also preformat numbers/dates. PDF reports already use mPDF and have access to `public/fonts/SolaimanLipi.ttf`. Spreadsheet headings and sheet titles are English literals. | | Notifications | Donation confirmations and recurring reminders are queued; callbacks/IPN and scheduled work cannot depend on the visitor's current session. | | Test discovery | `phpunit.xml` currently lists only `tests/Unit` and `tests/Feature`, while substantial existing coverage lives in `modules/*/Tests`. Account for this when selecting and running checks. | All 24 modules are in scope for interface review: Accounting, Acl, AdminAuth, Backup, Blog, Committee, ContactMessage, Dashboard, Donation, Faq, Gallery, Index, Menu, Newsletter, Notice, Notification, Page, Profile, Project, Settings, Slider, Support, User, and Volunteer. There are parallel starter files (`app.ts`, `vite.config.ts`, lowercase `pages`) alongside the active application (`app.js`, `vite.config.js`, uppercase `Pages`). Follow the entry points referenced by the current layouts and build; classify unused starter screens explicitly rather than treating them as live functionality. Avoid a frontend bootstrap migration as part of localization. ## 2. Locale behavior | Decision | Implementation | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Languages | Explicit allowlist: `bn` → `বাংলা`, `en` → `English`. Both use left-to-right layout. | | Default | Set the application configuration default and `.env.example` to Bangla; configure deployment `APP_LOCALE=bn`. Existing deployment environment values need an explicit update. | | Fallback | English fallback for missing Bangla entries, then a detectable missing-key result in development. Complete Bangla coverage is still a release requirement. | | Persistence | One shared browser preference for public and admin: valid session locale, then encrypted persistent cookie, then configured default. Cookie path `/`; retain preference through session regeneration and logout. | | First visit | Show Bangla. Browser language does not silently override the confirmed default. | | Switching | A named, CSRF-protected POST endpoint accepts only `bn` or `en`, saves the preference, and redirects to the current local GET page with its query string. Reject external return destinations. | | Admin UX | Switch through Inertia with component state and scroll preserved. Unsaved fields must survive; do not submit the current form. Refresh locale/catalog props, including in persistent layouts and partial visits. | | Public UX | A standard Blade form posts the selection and returns to the same page. It works without JavaScript. Include a return path because form submission loses URL fragments; preserve fragments only when practical on the client. | | URLs | Keep existing route paths, route names, slugs, payment callback URLs, and query/filter values. Distinct indexable language URLs are outside this interface-only phase. | | Cross-device preferences | Browser persistence meets this phase's scope. Saving an admin profile language can be added later without changing catalog architecture. | Add `SetLocale` after session availability and before translation-dependent application/authentication/validation and Inertia work. Inspect the effective middleware priority as well as array order. Consolidate the repeated `HandleInertiaRequests` registration in `bootstrap/app.php` while installing the locale middleware. ## 3. Translation architecture Use Laravel language files as the source for both PHP/Blade and Vue. Retain the existing `__()` template interface and `useTrans()` composable. No new translation dependency is required for this plan. New text uses stable, contextual keys, for example `common.save`, `auth.login.title`, `donation.payment.success`, and `accounting.reports.monthly_title`. Organize matching English/Bangla PHP catalogs by concern: common, admin, site, donation, accounting, settings, notifications, and CMS-specific groups where useful. Add Laravel `auth.php`, `passwords.php`, `validation.php`, and `pagination.php` for both locales. Keep application `lang/en.json` and `lang/bn.json` aliases for existing sentence-key calls during migration. Do not require a wholesale rewrite of working translated components just to introduce semantic keys. Override package-specific PHP messages under `lang/vendor/modular/{locale}` through application-owned files; never edit `vendor/`. Introduce a small catalog service under `modules/Support/Services` that: - Loads only explicitly approved public/admin UI groups for frontend delivery; does not expose settings values, credentials, or whole application configuration. - Preserves PHP group prefixes when flattening: `common.php` + `save` becomes `common.save`. - Merges fallback first and selected language second; within each language, package defaults precede application overrides. - Supplies the same resolved catalog contract to the admin middleware and public widget bootstrap, with separate group selections to limit payload size. - Uses a locale/catalog-version cache key, with deterministic invalidation when translations change. Retires the old `translations_{locale}` cache integration and documents deployment cleanup. Expose `locale`, `fallbackLocale`, `availableLocales`, and `translations` as namespaced Inertia shared data, such as `i18n`. These values must refresh on a language switch and must not be stored as permanent once-only props. Frontend `__()` must read reactive current values, handle absent boot data safely, and replace all occurrences of named placeholders. For public Vue widgets, safely serialize the same contract before mounting the app and install the shared translation plugin in `create-vue-app.js`. Use Laravel's safe JavaScript serialization rather than hand-built inline strings. Blade continues to call Laravel `__()` directly. Use complete translated sentences with placeholders, rather than concatenating translated fragments. Replace `useTitle()`'s current `Create` + section composition with complete contextual titles. Specify and test plural/count behavior in both runtimes; keep the helper limited to the forms actually used rather than building a general translation engine. Translate server flash messages once, on the server. Migrate `AppFlashMessage.vue` to display resolved messages, replacing its current attempt to translate arbitrary message text. For frontend-owned confirmations/toasts, use catalog keys directly. User data interpolated into messages stays escaped. ## 4. Language switchers Public navbar: - Add a reusable Blade language selector to the desktop header and the mobile navigation controls/drawer. - Display native language names, the current selection, a visible or accessible label, keyboard focus, and a submitting/disabled state where JavaScript enhances the form. - Keep the selector available at mobile widths; verify it does not collide with branding, Donate, theme, or menu controls. Admin navbar: - Add `AppLanguageSwitcher.vue` beside existing topbar actions and reuse it on authentication screens through `AppAuthShell.vue` or the guest layout. - Use a generated Wayfinder function for the new locale endpoint. The active JS Vite config does not currently install the Wayfinder plugin used by the starter TS config; generate the route helper explicitly or integrate only the required generation step. - Preserve form state, query filters, sidebar state, and scroll during Inertia switching. Compute translated labels/options so they react after setup, rather than translating once into constants. - Update the root document `lang`, translated page titles, breadcrumbs, sidebar labels, sidebar search matching, and chart labels when the locale changes. A root Blade `lang` attribute alone will not update on an Inertia visit. Use `বাংলা` / `English`, without national flags. Apply the existing public and admin theme conventions separately. ## 5. Complete interface conversion inventory | Work package | Text to convert and primary targets | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Shared admin shell | Topbar, sidebar/search, breadcrumbs, authentication, profile, document titles, developer-credit prefix, tooltips, icon button labels, alerts, confirmation dialogs, loading states. `Layouts`, `Components`, `Composables`, `Configs/menu.js`. Keep the gTechService brand and URL intact. | | Shared form/table controls | Labels, placeholders, validation summaries, select defaults/options, combobox empty/loading/search text, file upload states, rich-text toolbar titles/dialogs, pagination, record counts, no-results states, buttons. Inspect script defaults and accessibility attributes as well as visible template text. | | Donations and dashboard | Donation forms/funds/donors/recurring schedules, payment states/method labels, reports, chart legends/tooltips, dashboard metrics, filters, all action/result messages. | | Accounting | Transactions, categories, accounts, transfers, balances, income/expense labels, attachment previews, report periods, totals, exports, backend validation and action messages. | | CMS | Blog authors/categories/posts/tags, pages, notices, projects, galleries/categories, sliders, FAQs, menu builder. Translate editor instructions, metadata labels, visibility/status choices and recycle-bin operations. | | People and communication | Committee, volunteers/approval states, contact messages, newsletter, broadcast composer/logs, recipients, channels, delivery states. | | Administration | User/role/permission screens, profile/password, backup, every settings group including Branding, General, Homepage, Contact, Social, SEO, Mail, SMS, Pixel and Analytics. | | Public shared UI | Header, desktop/mobile navigation chrome, footer, breadcrumbs, home sections, carousel controls, newsletter bar, donation cards, image fallbacks, pagination, WhatsApp defaults. | | Public pages | Home, about/legal page chrome, contact, donation listing/detail/quick form/payment results, projects/detail, blog/archive/search/tag/detail, notice listing/detail, gallery, FAQ, volunteer registration. Audit `resources-site/views`, `resources-site/js`, and all `modules/*/views`. | | Backend responses | Controller redirects/flash, JSON/AJAX errors displayed to people, Form Request `messages()`/`attributes()`, custom validators, auth failures, reset password feedback, throttling and upload errors. | | Generated documents | Donation and accounting PDF headings/filters/totals/status labels; shared document header/footer/watermark text; spreadsheet headings, totals, month labels, worksheet titles. | | System communication | Password-reset email, contact email wrapper, donation confirmation and recurring email/SMS templates, broadcast wrapper, settings test email/SMS feedback. | Inventory both existing English and hardcoded Bangla strings. Review template text, component props/defaults, script arrays, inline Blade JavaScript, chart configuration, `title`, `alt`, `aria-label`, document metadata, and framework/package UI. Static-string searching assists the audit but requires manual classification. ### Database-backed text boundaries - Preserve custom menu labels, badge text, page/post bodies, titles, fund/project names, names of people, contact details, authored broadcast content, and editable branding/settings values. - Built-in seeded navigation labels are interface text despite being stored in the database. Add an optional `translation_key` to menu items for application-owned defaults; backfill only confidently identified, unchanged seeded items, using route/menu/parent/label signatures. Custom labels retain their current rendering. Expose a localized default/custom-label choice only if needed; do not add bilingual content fields in this phase. - Resolve built-in menu labels after retrieving the locale-neutral cached tree. If translated nodes are cached instead, include locale in every relevant cache/invalidation key. Cover nested menus, footer column headings, mobile menus, and badges with built-in defaults. - Settings definitions have seeded labels/descriptions. Translate those from stable group/key metadata while retaining editable values and deliberate custom definitions. Do the same for application-owned permission display labels while preserving underlying permission identifiers. - Translate fallback copy only when a saved content value is absent. Never pass arbitrary database content through `__()` in the hope it translates a complete page. - About/legal pages currently resolve stored `Page` content through `IndexController`; their interface can switch while the authored body remains in its original language. The same applies to slider text and site slogans. This is the confirmed scope. ## 6. Validation, formatting, reports, and background work Validation: - Supply complete English and Bangla validation/auth/password/pagination messages, localized field names, and project-specific rule messages. - Resolve `required_editor` at validation time. Its current provider-time `trans('modular::validation.required_editor')` can capture the boot locale before request middleware sets it. - Preserve validation rules and field keys; localize the displayed message and attribute names. Keep API status codes and machine-readable response values stable. - Translate application-owned payment failures and result messages. Keep provider diagnostics available for troubleshooting; map customer-visible results to stable localized messages rather than attempting to translate raw gateway text. Formatting: - Centralize display formatting using `bn-BD` and an explicit English locale suitable for Bangladesh, with BDT and the current application timezone policy. Language switching must not silently change timezone or financial values. - Audit existing `number_format`, `format`, `ucfirst(status)`, hardcoded month names, and fixed `en-US` chart formatting. For reactive admin displays, send raw numeric/date values where practical and format on rendering. - Use Bangla digits for Bangla display formatting where supported, while preserving ASCII dates/numbers in HTML control values, database writes, IDs, phone numbers, gateways, and machine data. Normalize Bangla numerals at user-facing numeric input boundaries if accepted; do not accidentally strip them through existing phone normalization. - Localize the displayed status/type/method label while preserving values such as `paid`, `income`, `ongoing`, and `bank` in requests, storage, and filters. - Add a Bangla-capable web font stack for both frontends. Check the existing SolaimanLipi asset for suitable use; verify real conjunct shaping, line height, navigation width, and dark mode. Reports: - Localize `resources/views/donation/report.blade.php`, `modules/Accounting/views/financial-report.blade.php`, shared document components, `DonationsExport`, `MonthlySummarySheet`, and `YearlySummarySheet`. - Preserve existing mPDF font registration and Bangla run handling; visually inspect generated Bangla output. Test worksheet headings/title values and keep numeric spreadsheet cells numeric. - Carry the selected locale explicitly if any export is queued later. Do not rely on a queue worker inheriting an HTTP request locale. Notifications: - Capture the locale on donation initiation and recurring setup so payment callbacks, IPN, and scheduled reminders can select it without a browser session. Add nullable/defaulted locale metadata to donation and recurring records, following existing module migration conventions; this is delivery metadata rather than bilingual content. - Dispatch donation notifications with the stored locale using Laravel's notification locale support. Resolve existing records to the configured default. Ensure locale is restored between jobs. - Use the current request locale for password-reset initiation and contact email wrapper generation. Carry a chosen locale in the queued broadcast job for system wrapper text; authored subject/body are preserved. - A later donor/profile language preference can override future message selection if requested. Do not infer a donor's preference from an unrelated administrator's browser. ## 7. Implementation order and reviewable deliverables | Phase | Deliverable | Exit condition | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | 1. Catalog and locale foundation | Supported locale configuration, catalog contract/service, `SetLocale`, validated switch endpoint, initial common/auth dictionaries, focused feature coverage. | Bangla default and English selection work on Blade and Inertia responses; invalid locales and unsafe redirects are rejected. | | 2. Frontend integration and switchers | Reactive admin plugin/composable, public widget bootstrap, both navbar switchers, guest selector, document language/title updates. | Switching in both directions works on desktop/mobile; an unsaved admin form retains data. | | 3. Shared controls and navigation | All shared UI and titles, menu search, built-in public menu metadata/backfill, settings/permission label mapping. | Common UI and built-in navigation translate consistently; custom content and permission checks remain correct. | | 4. Public site | Translate all public views/widgets, form feedback and payment-result UI. | Every public route family is reviewed in both languages, including empty/error states. | | 5. Admin modules and backend feedback | Work through every module using the inventory above; convert static strings, options, controller feedback, validation, and dashboard charts. | Every live admin page and shared modal is reviewed in both languages; catalog key/placeholder parity passes. | | 6. Documents and communication | Formatting helpers/fonts, bilingual PDF/Excel labels, email/SMS templates, stored delivery locale and queue propagation. | Representative outputs render correctly; background messages use the intended locale. | | 7. Regression and release | Remaining literal audit, translation review, browser checks, production cache/build procedure. | Acceptance checks below pass; no unexplained untranslated application-owned interface text remains. | Phases 1–2 establish the infrastructure but do not complete the requested feature. Completion includes all module conversions, validation, documents, and communication listed above. ## 8. Expected file changes | Paths | Intended change | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `config/app.php`, `.env.example` | Default Bangla, fallback English, allowlisted locale metadata in configuration. | | `app/Http/Middleware/SetLocale.php`, `bootstrap/app.php` | Resolve locale early and consolidate middleware registration. | | `modules/Support/Services/*`, `modules/Support/Http/Controllers/*`, `modules/Support/Http/Requests/*`, `modules/Support/routes/site.php` | Catalog construction and named public switch endpoint, following existing module structure. Register any command/provider work explicitly. | | `lang/en/*`, `lang/bn/*`, `lang/en.json`, `lang/bn.json`, applicable `lang/vendor/modular/*` | Catalogs, compatibility aliases, framework and package message overrides. | | `app/Http/Middleware/HandleInertiaRequests.php`, `resources/views/app.blade.php` | Shared reactive i18n props and retirement of the old global loader. | | `resources/js/Plugins/Translations.js`, `Composables/useTrans.js`, `Composables/useTitle.js`, applicable TS declarations | Reactive lookup, interpolation, contextual titles, documented frontend contract. | | `resources/js/Components/Misc/AppTopBar.vue`, new switcher component, auth shell/guest layout | Admin and unauthenticated language controls. | | `resources-site/views/site-layout.blade.php`, `components/header.blade.php`, new selector component, `resources-site/js/create-vue-app.js` | Public controls and safely bootstrapped widget translations. | | `modules/Menu/*`, targeted module migrations | Translation metadata for built-in menus and locale-safe cache behavior. | | `modules/Donation/*`, targeted module migrations, notification jobs/mail | Recorded delivery locale and localized messages. | | `resources/js/Pages/**`, `resources/js/Components/**`, `resources-site/**`, `modules/**` | Static interface conversion across every inventoried surface. | | `resources/css/app.css`, `resources-site/css/site.css`, report templates | Bangla-capable typography and display formatting. | | `tests/Feature/*`, relevant `modules/*/Tests/*`, optionally `phpunit.xml` | Locale behavior and output coverage; ensure module tests are actually selected/discovered. | Use existing directories and Laravel generators for new PHP files. No dependency additions or edits to vendor code are planned. Preserve existing unrelated work in the working tree. ## 9. Verification and acceptance Automated coverage should prove behavior rather than mirror implementation: 1. A clean visitor gets Bangla; switching to English persists across navigation, refresh, login/session regeneration, and return visits. Two browser sessions can use different languages without leakage. 2. Invalid/missing locale submissions do not corrupt the saved preference. Unsupported stored values fall back safely; off-site redirect destinations are rejected; the endpoint remains CSRF protected. 3. Public HTML and admin Inertia payloads agree on the locale. Partial visits and the language-switch response provide current catalogs; admin root `lang` and titles update. 4. English/Bangla keys and placeholder sets match. Fallback works; a missing Bangla entry is detectable rather than silently accepted as finished work. Application overrides beat package defaults, including with production-style caching. 5. Existing `__()`/`useTrans()` call sites work; repeated placeholders and dynamic names render correctly and safely. 6. Validation, custom validators, auth feedback, controller flash and public AJAX feedback use the selected language. Machine values and permission checks remain unchanged. 7. Built-in menus translate after a cache has already been warmed in the other language. Custom labels survive; nested/mobile/footer menus remain functional. 8. Notification dispatch preserves the selected locale through queued execution, callback/IPN, and scheduled recurring work. Different-locale jobs do not leak state. 9. Generated PDF and spreadsheet content contains selected-language labels. Test actual workbook contents for headings/titles, since an export-dispatch fake alone cannot prove localization. Financial values remain unchanged. Browser review must cover public desktop/mobile headers, admin desktop/mobile topbars, auth pages, sidebar search, unsaved forms, empty/search/error states, tooltips, modals, charts, pagination, light/dark themes, and Bangla glyph shaping. Review the whole route/page inventory; sample end-to-end flows include donation/payment-result, contact, volunteer registration, login/reset password, accounting entry, and report download. Recheck recent browser logs for runtime/missing-catalog errors. Run focused Pest tests after each phase. Explicitly include affected module test directories because the current default configuration omits them; verify/fix discovery before calling a run comprehensive. Run formatting/lint/type checks and `npm run build` for the active frontend. Run `vendor/bin/pint --dirty --format agent` after PHP edits. After focused feature checks pass, request the project-wide `php artisan test --compact` run, with module discovery included or an explicit separate module suite command. For release, configure `APP_LOCALE=bn` and `APP_FALLBACK_LOCALE=en`, apply additive metadata migrations, rebuild configuration/assets, invalidate/version translation and affected menu caches, and restart workers so they load current catalogs/code. Smoke-test both locales against production-style caching. A rollback can restore the prior UI/code while leaving additive metadata columns in place. ## 10. Scope boundary and references This phase makes all application-owned interface strings available in Bangla and English. It does not translate stored articles, legal page bodies, custom menu labels, fund names, branding values, or authored messages. Adding bilingual content editing, localized slugs/URLs, translated-content search, hreflang, and per-language SEO content requires a separate content-localization design. The plan follows the installed versions and primary documentation consulted through Laravel Boost: [Laravel localization](https://laravel.com/docs/13.x/localization), [localized notifications](https://laravel.com/docs/13.x/notifications#localizing-notifications), [localized mail](https://laravel.com/docs/13.x/mail#localizing-mailables), and [Inertia v3 shared data](https://inertiajs.com/docs/v3/data-props/shared-data). Package loader behavior was also checked directly against the installed Modular source.