docs: Add language-agnostic for Playwright testing doc

Author: hienha-sw

guides/plugins/plugins/testing/playwright/language-agnostic-testing.md

@@ -0,0 +1,375 @@
+---
+nav:
+    title: Language Agnostic Testing
+    position: 20
+---
+
+# Language Agnostic Testing in @shopware-ag/acceptance-test-suite
+
+Language agnostic testing allows you to write acceptance tests that work across different languages without hardcoding text strings. Tests use translation keys instead of hardcoded strings and automatically adapt to different locales via environment variables.
+
+## translate() Function
+
+Use the `translate()` function in page objects to replace hardcoded strings with translation keys.
+
+### Usage in Page Objects
+
+```typescript
+import { translate } from '../../services/LanguageHelper';
+
+export class CategoryListing implements PageObject {
+    constructor(page: Page) {
+        this.createButton = page.getByRole('button', {
+            name: translate('administration:category:actions.createCategory'),
+        });
+    }
+}
+```
+
+## Translate Fixture
+
+The `Translate` fixture provides translation functionality in tests.
+
+### Usage in Tests
+
+```typescript
+import { test, expect } from '@shopware-ag/acceptance-test-suite';
+
+test('Category creation', async ({ AdminPage, Translate }) => {
+    const saveText = Translate('administration:category:general.save');
+    await AdminPage.getByRole('button', { name: saveText }).click();
+});
+```
+
+## Environment Control
+
+Switch test language using environment variables:
+
+```bash
+LANG=de npm run test  # German
+LANG=en npm run test  # English (default)
+```
+
+## Translation Keys
+
+Translation keys follow the pattern: `area:module:section.key`
+
+### Examples
+
+```typescript
+'administration:category:general.save';
+'administration:category:actions.createCategory';
+'storefront:account:fields.firstName';
+'storefront:checkout:payment.invoice';
+```
+
+### Locale Files
+
+Translations are stored in JSON files organized by language and area:
+
+-   `locales/en/administration/category.json`
+-   `locales/de/administration/category.json`
+-   `locales/en/storefront/account.json`
+-   `locales/de/storefront/account.json`
+
+### Example Translation Files
+
+**English (`locales/en/administration/category.json`):**
+
+```json
+{
+    "general": {
+        "save": "Save",
+        "cancel": "Cancel"
+    },
+    "actions": {
+        "createCategory": "Create category"
+    }
+}
+```
+
+**German (`locales/de/administration/category.json`):**
+
+```json
+{
+    "general": {
+        "save": "Speichern",
+        "cancel": "Abbrechen"
+    },
+    "actions": {
+        "createCategory": "Kategorie erstellen"
+    }
+}
+```
+
+## Supported Locales
+
+**Translation Resources**: `en` (English), `de` (German)  
+**Browser UI**: `en`, `de`, `fr`, `es`, `it`, `nl`, `pt`
+
+## Common Issues
+
+**Translation key not found:**
+
+-   Verify key exists in both EN/DE locale files
+-   Check import in `locales/index.ts`
+-   Ensure proper namespace structure
+
+**Tests fail with LANG changes:**
+
+-   Move `translate()` calls inside constructors/functions, not at module level
+-   Ensure translation resources are properly loaded
+
+**JSON import errors:**
+
+-   Always use `with { type: 'json' }` import attribute
+-   Check file paths and naming conventions
+
+**Browser locale not matching:**
+
+-   Verify locale mapping in `playwright.config.ts`
+-   Check browser args configuration
+-   Ensure language detection is working correctly
+
+## Using in Your Own Project
+
+If you want to use the `@shopware-ag/acceptance-test-suite` in your own project with custom translations, you can extend the base test suite with your own translation fixture.
+
+### Installation
+
+First, install the required dependencies:
+
+```bash
+npm install @shopware-ag/acceptance-test-suite @playwright/test
+npm install -D @types/node
+```
+
+### Create Custom Translation Fixture
+
+Create a new fixture file (e.g., `fixtures/CustomTranslation.ts`):
+
+```typescript
+import {
+    test as base,
+    LanguageHelper,
+    TranslationKey,
+    TranslateFn,
+    BUNDLED_RESOURCES,
+    baseNamespaces,
+} from '@shopware-ag/acceptance-test-suite';
+import { LOCALE_RESOURCES, enNamespaces } from '../locales';
+
+// Merge base BUNDLED_RESOURCES with your custom LOCALE_RESOURCES
+const MERGED_RESOURCES = {
+    en: { ...BUNDLED_RESOURCES.en, ...LOCALE_RESOURCES.en },
+    de: { ...BUNDLED_RESOURCES.de, ...LOCALE_RESOURCES.de },
+} as const;
+
+// Merge base and custom namespaces
+const mergedNamespaces = {
+    ...baseNamespaces,
+    ...enNamespaces,
+} as const;
+
+type CustomTranslationKey = TranslationKey<typeof mergedNamespaces>;
+
+interface CustomTranslateFixture {
+    Translate: TranslateFn<CustomTranslationKey>;
+}
+
+export const test = base.extend<CustomTranslateFixture>({
+    Translate: async ({}, use) => {
+        let lang = process.env.lang || process.env.LANGUAGE || process.env.LANG || 'en';
+        let language = lang.split(/[_.-]/)[0].toLowerCase();
+
+        if (!MERGED_RESOURCES[language as keyof typeof MERGED_RESOURCES]) {
+            console.warn(
+                `⚠️  Translation resources for '${language}' not available. Supported: ${Object.keys(
+                    MERGED_RESOURCES
+                ).join(', ')}. Falling back to 'en'.`
+            );
+            language = 'en';
+        }
+
+        const languageHelper = await LanguageHelper.createInstance(
+            language,
+            MERGED_RESOURCES as unknown as typeof BUNDLED_RESOURCES
+        );
+
+        const translate: TranslateFn<CustomTranslationKey> = (key, options) => {
+            return languageHelper.translate(key as TranslationKey, options);
+        };
+
+        await use(translate);
+    },
+});
+
+export * from '@shopware-ag/acceptance-test-suite';
+export type { CustomTranslationKey };
+```
+
+### Create Locale Files Structure
+
+Organize your translation files by language and area:
+
+```
+project-root/
+├── locales/
+│   ├── en/
+│   │   ├── administration/
+│   │   │   ├── common.json
+│   │   │   └── product.json
+│   │   └── storefront/
+│   │       ├── account.json
+│   │       └── checkout.json
+│   ├── de/
+│   │   ├── administration/
+│   │   │   ├── common.json
+│   │   │   └── product.json
+│   │   └── storefront/
+│   │       ├── account.json
+│   │       └── checkout.json
+│   └── index.ts
+├── fixtures/
+│   └── CustomTranslation.ts
+├── types/
+│   └── TranslationTypes.ts
+└── tests/
+    └── your-test.spec.ts
+```
+
+### Create Locales Index
+
+Create `locales/index.ts` to import and export your translation files:
+
+```typescript
+// Import all locale files
+import enAdministrationCommon from './en/administration/common.json' with { type: 'json' };
+import enStorefrontAccount from './en/storefront/account.json' with { type: 'json' };
+
+import deAdministrationCommon from './de/administration/common.json' with { type: 'json' };
+import deStorefrontAccount from './de/storefront/account.json' with { type: 'json' };
+
+// Export the bundled resources for i18next
+export const LOCALE_RESOURCES = {
+    en: {
+        'administration/common': enAdministrationCommon,
+        'storefront/account': enStorefrontAccount,
+    },
+    de: {
+        'administration/common': deAdministrationCommon,
+        'storefront/account': deStorefrontAccount,
+    },
+} as const;
+
+export const enNamespaces = {
+    administration: {
+        common: enAdministrationCommon,
+    },
+    storefront: {
+        account: enStorefrontAccount,
+    },
+} as const;
+```
+
+### Create Translation Types
+
+Create `types/TranslationTypes.ts` to define your custom translation types. This provides:
+
+-   **Type Safety**: Ensures translation keys exist in your locale files
+-   **IntelliSense**: Auto-completion for available translation keys
+-   **Compile-time Validation**: Catches typos and missing keys before runtime
+
+```typescript
+import { TranslationKey, TranslateFn } from '@shopware-ag/acceptance-test-suite';
+import { enNamespaces } from '../locales';
+
+export type CustomTranslationKey = TranslationKey<typeof enNamespaces>;
+
+export type CustomTranslateFn = TranslateFn<CustomTranslationKey>;
+```
+
+### Merge with Base Test Suite
+
+Create your main test fixture that merges the base test suite with your custom translation:
+
+```typescript
+import { test as ShopwareTestSuite, mergeTests } from '@shopware-ag/acceptance-test-suite';
+import { test as CustomTranslation } from './fixtures/CustomTranslation';
+
+export * from '@shopware-ag/acceptance-test-suite';
+
+export const test = mergeTests(ShopwareTestSuite, CustomTranslation);
+```
+
+**Note**: Save this as `test.ts` or `index.ts` in your project root and import it in your test files.
+
+### Usage in Your Tests
+
+Now you can use the `Translate` fixture in your tests:
+
+```typescript
+import { test } from './your-main-test-fixture';
+
+test('My localized test', async ({ Translate, AdminPage }) => {
+    const saveText = Translate('administration:common:button.save');
+    await AdminPage.getByRole('button', { name: saveText }).click();
+});
+```
+
+### Environment Configuration
+
+Set up your Playwright configuration to support language switching:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+const LOCALES = { de: 'de-DE', en: 'en-US', fr: 'fr-FR' };
+
+function getLanguage(): string {
+    let lang = process.env.lang || process.env.LANGUAGE || process.env.LANG || 'en';
+    return lang.split(/[_.-]/)[0].toLowerCase();
+}
+
+function getLocaleConfig() {
+    const lang = getLanguage();
+    const browserLocale = LOCALES[lang as keyof typeof LOCALES] || 'en-US';
+    const browserArgs =
+        lang !== 'en' && LOCALES[lang as keyof typeof LOCALES]
+            ? [`--lang=${browserLocale}`, `--accept-lang=${browserLocale},${lang};q=0.9,en;q=0.8`]
+            : [];
+
+    return { lang, browserLocale, browserArgs };
+}
+
+export default defineConfig({
+    use: {
+        locale: getLocaleConfig().browserLocale,
+    },
+    projects: [
+        {
+            name: 'Platform',
+            use: {
+                ...devices['Desktop Chrome'],
+                launchOptions: {
+                    args: [...getLocaleConfig().browserArgs],
+                },
+            },
+        },
+    ],
+});
+```
+
+### Running Tests with Different Languages
+
+```bash
+# German
+lang=de npx playwright test
+
+# English (default)
+npx playwright test
+
+# Using system environment
+LANG=de npx playwright test
+```