Bite 31.1 — I18N Foundation and Locale Contract - RodrigoMattosoSilveira/EnterpriseRemoteSystems GitHub Wiki

Bite 31.1 — I18N Foundation and Locale Contract

Manual Verification Before Promotion

Branch: 860-bite-311-i18n-foundation-and-locale-contract
SHA: 4912a415571ee7fa5fbaeaed2e370c47c9ebc497

Scope of this manual suite

Bite 31.1 establishes the localization runtime and locale contract only.

It intentionally does not:

  • translate the existing ERS application screens;
  • provide a visible language selector;
  • translate Administration, People, Collaborators, Planning, Expenses, Receipts, or other business workflows.

Therefore, seeing the existing ERS UI remain in English during these tests is expected and is not a failure.

The manual verification concentrates on:

  1. locale initialization in a real browser;
  2. explicit locale persistence;
  3. <html lang> synchronization;
  4. isolation of locale preference from authentication and Administration/Tenant context;
  5. browser-language fallback;
  6. synchronization between two browser tabs.

DevTools is used because Bite 31.1 intentionally has no visible locale-selection UI yet.

Common prerequisites

Use the normal LOCAL environment that already passed make local-check.

For tests requiring authentication, use:

  • Identity: Application Administrator
  • Login: [email protected]
  • Password: Local-E2E-Administrator-28D!
  • Required Administration context: Global administration

Before beginning:

  1. Start the normal LOCAL backend and frontend.
  2. Open the ERS application in Chrome.
  3. Open Chrome DevTools.
  4. Confirm the application loads without an uncaught JavaScript error.
  5. Sign in as [email protected].
  6. Confirm the application shows Global administration as the current Administration context.
  7. Do not create or approve a Support Access Lease during this suite.

Test 01 — Default locale initialization and document language

Purpose

Verify that the I18N provider initializes in a real browser and synchronizes the selected locale to the HTML document.

Identity

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context: Global administration

Prerequisite

Remove any previously stored ERS locale preference.

Steps

  1. With ERS open, open Chrome DevTools.

  2. Select the Application tab.

  3. In the left pane, expand Local Storage.

  4. Select the LOCAL ERS origin.

  5. Locate the key:

    ers.i18n.locale

  6. If the key exists, delete it.

  7. Select the Console tab.

  8. Execute:

    navigator.languages

  9. Record the returned browser language list.

  10. Determine the expected ERS locale using this exact rule:

    • first en or en-US encountered → expected en-US;
    • first pt or pt-BR encountered → expected pt-BR;
    • pt-PT does not count as pt-BR;
    • unsupported languages are skipped;
    • if no supported language is present → expected en-US.

  11. Reload the ERS page.

  12. If necessary, sign in again as [email protected].

  13. Confirm the application still loads normally.

  14. In DevTools Console, execute:

    document.documentElement.lang

  15. Record the returned value.

Expected result

  • √ document.documentElement.lang equals the locale determined in Step 10.
  • √ The application loads successfully.
  • √ No localization-related error appears in the Console.
  • √ The existing ERS screen text may still be English.
  • √ Authentication remains valid.
  • √ The selected Administration context remains Global administration.

PASS criteria

PASS if:

  • √ the HTML lang attribute matches the locale-resolution rule;
  • √ ERS remains operational;
  • √ authentication and Administration context are unchanged.

Promotion blocker

Do not promote if:

  • <html lang> is empty;
  • <html lang> contains an unsupported locale;
  • ERS fails to load after the locale provider initializes;
  • authentication or Administration context changes merely because the locale initializes.

Test 02 — Explicit Brazilian Portuguese preference persists across reload

Purpose

Verify that an explicit pt-BR preference overrides browser-language resolution, survives reload, and remains presentation-only state.

Identity

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context before change: Global administration

Steps

  1. Confirm you are signed in as [email protected].

  2. Confirm the current context is Global administration.

  3. Record the currently displayed signed-in identity.

  4. Record the currently selected Administration context.

  5. Open DevTools Console.

  6. Execute:

    localStorage.setItem("ers.i18n.locale", "pt-BR")

  7. Reload the page.

  8. Wait for ERS to finish loading.

  9. In the Console, execute:

    localStorage.getItem("ers.i18n.locale")

  10. Confirm the result is:

    pt-BR

  11. Execute:

    document.documentElement.lang

  12. Confirm the result is:

    pt-BR

  13. Inspect the ERS top bar.

  14. Confirm the signed-in identity is still the same Application Administrator recorded before the change.

  15. Confirm the current Administration context is still Global administration.

  16. Open the Administration context selector.

  17. Confirm changing the locale preference did not create or expose an ordinary Tenant identity for the Application Administrator.

  18. Close the selector without changing context.

  19. Navigate through at least two ordinary application pages using the visible UI.

  20. Confirm navigation continues to work.

Expected result

  • √ ers.i18n.locale remains pt-BR.
  • √ <html lang> is pt-BR.
  • √ The locale survives page reload.
  • √ Authentication Account/Actor identity is unchanged.
  • √ Administration context remains Global administration.
  • √ No Tenant, Membership, Collaborator, Support Access Lease, or authorization capability is created by changing locale.
  • √ Existing screen strings may remain English because translation of those screens is outside Bite 31.1.

PASS criteria

PASS if the explicit Brazilian Portuguese preference persists and affects only presentation locale state.

Promotion blocker

Do not promote if changing locale:

  • signs the user out unexpectedly;
  • changes the current Actor;
  • changes the Administration/Tenant context;
  • exposes an ordinary Tenant identity;
  • changes authorization behavior;
  • fails to persist;
  • fails to update <html lang>.

Test 03 — Explicit English preference replaces Brazilian Portuguese preference

Purpose

Verify that ERS can explicitly move between the two supported locales and persist the replacement preference.

Identity

Continue as:

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context: Global administration

Prerequisite

Test 02 has completed and ers.i18n.locale currently contains pt-BR.

Steps

  1. Open DevTools Console.

  2. Execute:

    localStorage.setItem("ers.i18n.locale", "en-US")

  3. Reload ERS.

  4. Wait for the application to load.

  5. Execute:

    localStorage.getItem("ers.i18n.locale")

  6. Confirm the result is:

    en-US

  7. Execute:

    document.documentElement.lang

  8. Confirm the result is:

    en-US

  9. Confirm you are still signed in as the same Application Administrator.

  10. Confirm the selected Administration context is still Global administration.

  11. Navigate to another page through the visible ERS navigation.

  12. Confirm the page loads successfully.

Expected result

  • √ the stored locale changes from pt-BR to en-US;
  • √ <html lang> becomes en-US;
  • √ the new value persists after reload;
  • √ business/application state is unchanged.

PASS criteria

√ PASS if explicit locale replacement works and remains isolated from ERS identity and business state.

Promotion blocker

Do not promote if:

  • the previous pt-BR locale remains active after reload;
  • <html lang> does not become en-US;
  • changing the locale changes identity;
  • changing the locale changes Administration/Tenant context;
  • changing the locale changes business data.

Test 04 — Locale preference synchronizes to another open ERS tab

Purpose

Verify the Bite 31.1 cross-tab locale synchronization behavior in an actual browser.

Identity

Both tabs must use the same authenticated LOCAL ERS session:

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context: Global administration

Prerequisite

ers.i18n.locale is currently en-US.

Steps

  1. In Chrome, open the LOCAL ERS application in Tab A.

  2. Open the same ERS application origin in Tab B.

  3. Confirm both tabs are signed in as the Application Administrator.

  4. Confirm both tabs show Global administration.

  5. In Tab B, open DevTools Console.

  6. Execute:

    document.documentElement.lang

  7. √ Confirm Tab B currently reports:

    en-US

  8. Leave Tab B open.

  9. Return to Tab A.

  10. Open DevTools Console in Tab A.

  11. Execute:

    localStorage.setItem("ers.i18n.locale", "pt-BR")

  12. Do not reload Tab B.

  13. Return to Tab B.

  14. In Tab B's Console, execute:

    document.documentElement.lang

  15. Confirm Tab B now reports:

    pt-BR

  16. Confirm Tab B remains signed in.

  17. Confirm Tab B still shows Global administration.

  18. Navigate to another ERS page from Tab B using the visible UI.

  19. Confirm normal operation.

Expected result

  • Tab B updates to pt-BR without a page reload.
  • The locale change propagates through the browser storage event.
  • Authentication state remains intact.
  • Administration context remains unchanged.
  • No application error occurs.

PASS criteria

PASS if Tab B changes its document language to pt-BR without reload and retains the same ERS identity/context.

Promotion blocker

Do not promote if:

  • Tab B remains en-US;
  • Tab B must be reloaded before the locale changes;
  • cross-tab synchronization causes an application error;
  • authentication changes;
  • Administration/Tenant context changes.

Test 05 — Removing the explicit preference returns ERS to browser-language resolution

Purpose

Verify the documented distinction between an explicit ERS locale preference and browser-controlled locale selection.

Identity

Continue as:

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context: Global administration

Steps

  1. Open DevTools Console.

  2. Execute:

    navigator.languages

  3. Record the returned list.

  4. Determine the expected ERS browser-derived locale using this exact rule:

    • en or en-US → en-US;
    • pt or pt-BR → pt-BR;
    • pt-PT is unsupported and must not be treated as pt-BR;
    • unsupported languages are skipped;
    • if none match, fallback is en-US.

  5. Execute:

    localStorage.removeItem("ers.i18n.locale")

  6. Reload ERS.

  7. Wait for ERS to finish loading.

  8. Execute:

    localStorage.getItem("ers.i18n.locale")

  9. Confirm the result is:

    null

  10. Execute:

    document.documentElement.lang

  11. Compare the returned locale with the expected locale calculated in Step 4.

  12. Confirm you remain signed in as the Application Administrator.

  13. Confirm the Administration context remains Global administration.

Expected result

  • there is no explicit ers.i18n.locale value;
  • ERS resolves the locale from the browser language list;
  • unsupported regional variants are not silently converted into another dialect;
  • if no supported locale is found, ERS uses en-US;
  • identity and context remain unchanged.

PASS criteria

PASS if the locale follows the documented browser-resolution/fallback rule after the explicit preference is removed.

Promotion blocker

Do not promote if:

  • an unsupported locale becomes the document language;
  • pt-PT is silently interpreted as pt-BR;
  • ERS fails instead of falling back to en-US;
  • authentication changes;
  • Administration/Tenant context changes.

Test 06 — Unsupported stored locale cannot become the active ERS locale

Purpose

Verify that manually corrupted or obsolete stored locale values cannot put ERS into an unsupported locale state.

Identity

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context: Global administration

Steps

  1. Confirm you are signed in as the Application Administrator.

  2. Confirm the selected context is Global administration.

  3. Open DevTools Console.

  4. Execute:

    localStorage.setItem("ers.i18n.locale", "fr-FR")

  5. Reload the page.

  6. Wait for ERS to finish loading.

  7. Execute:

    document.documentElement.lang

  8. Record the returned locale.

  9. Execute:

    localStorage.getItem("ers.i18n.locale")

  10. Record the stored value.

  11. Confirm the active document language is not fr-FR.

  12. Confirm the active document language is one of:

    en-US
pt-BR

  13. Confirm ERS remains usable.

  14. Confirm you remain signed in.

  15. Confirm the Administration context remains Global administration.

Expected result

  • unsupported fr-FR never becomes the active ERS locale;
  • ERS resolves to a supported browser locale or to en-US fallback;
  • the application does not crash because Local Storage contains an unsupported value;
  • identity and authorization state remain unchanged.

PASS criteria

PASS if the unsupported stored locale is safely rejected as an active locale.

Promotion blocker

Do not promote if:

  • <html lang> becomes fr-FR;
  • application startup fails;
  • an uncaught I18N error appears;
  • authentication or context changes.

Test 07 — Locale state is presentation state only

Purpose

Verify explicitly that locale changes do not alter ERS identity or authorization state.

Identity

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context: Global administration

Steps

  1. Sign in as [email protected].

  2. Confirm Global administration is selected.

  3. Open the Administration context selector.

  4. Record every context currently available to the Application Administrator.

  5. Close the selector without changing the selection.

  6. Open DevTools Console.

  7. Execute:

    localStorage.setItem("ers.i18n.locale", "pt-BR")

  8. Reload ERS.

  9. Confirm <html lang> is pt-BR.

  10. Open the Administration context selector.

  11. Compare the available contexts with those recorded in Step 4.

  12. Close the selector.

  13. In DevTools Console, execute:

    localStorage.setItem("ers.i18n.locale", "en-US")

  14. Reload ERS.

  15. Confirm <html lang> is en-US.

  16. Open the Administration context selector again.

  17. Compare the available contexts again with those recorded in Step 4.

Expected result

The locale change does not:

  • create a Tenant Actor;
  • create a Person;
  • create a Membership;
  • create a Collaborator;
  • create a Role Grant;
  • create a Support Access Lease;
  • expose an additional Tenant context;
  • remove a legitimately available context;
  • alter the selected Administration context.

PASS criteria

PASS if the exact Administration context choices remain unchanged across locale changes.

Promotion blocker

Any identity, Tenant, Membership, Collaborator, Role Grant, Support Lease, or authorization difference caused solely by locale selection blocks promotion.

Test 08 — Final application regression observation

Purpose

Confirm that introducing the global I18N provider has not destabilized ordinary ERS navigation.

Identity

  • Role: Application Administrator
  • Login: [email protected]
  • Administration context: Global administration

Steps

  1. Set the locale to either supported value:

    localStorage.setItem("ers.i18n.locale", "pt-BR")

    or:

    localStorage.setItem("ers.i18n.locale", "en-US")

  2. Reload ERS.

  3. Using only visible UI navigation, open the normal landing/home page.

  4. Confirm the page renders.

  5. Using visible UI navigation, open Administration.

  6. Confirm the page renders.

  7. Using visible UI navigation, open Tenants or another normal Administration page available to the Application Administrator.

  8. Confirm the page renders.

  9. Open the Administration context selector.

  10. Confirm the selector opens and behaves normally.

  11. Close it without changing the selection.

  12. Open DevTools Console.

  13. Confirm there are no uncaught exceptions related to:

    • I18nProvider;
    • translations;
    • locale resolution;
    • formatting;
    • Local Storage synchronization.

Expected result

  • normal application navigation continues to operate;
  • no blank screen appears;
  • no provider initialization error appears;
  • the Administration context selector continues working;
  • the selected locale remains reflected in <html lang>.

PASS criteria

PASS if normal ERS operation remains stable with the I18N provider installed.

Promotion blocker

Do not promote if:

  • any normal page becomes inaccessible;
  • the application renders a blank screen;
  • the Administration context selector regresses;
  • a repeatable uncaught I18N exception appears.

Final cleanup after manual testing

Before ending the manual test session:

  1. Open DevTools Console.

  2. Remove the manually forced locale:

    localStorage.removeItem("ers.i18n.locale")

  3. Reload ERS.

  4. Confirm ERS returns to browser-language resolution.

  5. Confirm the application remains operational.

This cleanup prevents manual locale state from unintentionally affecting subsequent manual test suites.

Overall PASS criteria

Bite 31.1 manual verification is PASS only if all of the following are true:

  • Test 01 passes.
  • Test 02 passes.
  • Test 03 passes.
  • Test 04 passes.
  • Test 05 passes.
  • Test 06 passes.
  • Test 07 passes.
  • Test 08 passes.
  • en-US and pt-BR are the only active supported locales.
  • Explicit locale preference persists across reload.
  • Removing the preference returns ERS to browser locale resolution.
  • Unsupported locale values do not become active ERS locales.
  • <html lang> remains synchronized with the resolved locale.
  • Cross-tab locale synchronization works.
  • Locale state does not alter Authentication Account, Actor, Person, Tenant Membership, Collaborator, Role Grant, Support Access Lease, or authorization state.
  • Normal ERS navigation remains operational.
  • No repeatable I18N-related browser error occurs.

Promotion-blocking conditions

Do not promote Bite 31.1 if any of the following occurs:

  • application startup fails because of I18nProvider;
  • <html lang> does not reflect the resolved locale;
  • an unsupported locale becomes active;
  • explicit locale preference does not persist;
  • removal of explicit preference does not return to browser/fallback resolution;
  • cross-tab locale synchronization fails;
  • changing locale affects authentication;
  • changing locale affects authorization;
  • changing locale changes the selected Tenant or Administration context;
  • locale initialization creates or exposes an identity that did not exist before;
  • normal application navigation regresses;
  • an uncaught localization-related browser error is reproducible.

Promotion decision

If:

  • all LOCAL automated tests pass;
  • all CI tests pass;
  • this entire manual suite passes;

then Bite 31.1 — I18N Foundation and Locale Contract is ready for promotion.

⚠️ **GitHub.com Fallback** ⚠️