# i18n Integration

How to configure translations for `ui` with the dedicated `ui/ngx-translate` adapter and how to wire your own translation runtime.

## Setup with ngx-translate

This is the recommended setup when your host app already uses @ngx-translate/core.

```ts
import { ApplicationConfig, inject, provideAppInitializer } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import { provideTranslateService, TranslateService } from '@ngx-translate/core';
import { provideTranslateHttpLoader } from '@ngx-translate/http-loader';
import { provideUiI18nWithNgxTranslate } from 'ui/ngx-translate';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
    provideTranslateService({
      lang: 'en',
      fallbackLang: 'en',
      loader: provideTranslateHttpLoader({
        prefix: '/i18n/',
        suffix: '.json',
      }),
    }),
    provideUiI18nWithNgxTranslate({ prefix: 'ui' }),
    provideAppInitializer(() => {
      const translate = inject(TranslateService);
      return firstValueFrom(translate.use('en'));
    }),
  ],
};
```

## Translation keys structure

Keep keys under ui.* (or your configured prefix), so components can resolve defaults consistently.

```ts
{
  "ui": {
    "field": {
      "file": {
        "uploadText": "Click to upload or drag and drop",
        "singleFileHint": "Single file only",
        "multipleFilesHint": "Multiple files allowed",
        "filesSelected": "{{count}} files selected",
        "clearFilesAriaLabel": "Clear files",
        "removeFileAriaLabel": "Remove {{name}}"
      }
    }
  }
}
```

## Use without ngx-translate

The library core is translation-runtime agnostic. You can plug your own service via UI_TRANSLATE_FN.

```ts
import { makeEnvironmentProviders } from '@angular/core';
import { provideUiI18n, UI_TRANSLATE_FN } from 'ui';
import { MyTranslationService } from './my-translation.service';

export function provideUiI18nWithCustomService() {
  return makeEnvironmentProviders([
    provideUiI18n({ prefix: 'ui' }),
    {
      provide: UI_TRANSLATE_FN,
      deps: [MyTranslationService],
      useFactory: (service: MyTranslationService) => {
        return (key: string, params?: Record<string, unknown>) =>
          service.translateInstant(key, params);
      },
    },
  ]);
}
```

## Production checklist

- Use 'ui/ngx-translate' import for ngx adapter.
- Keep your keys under the configured prefix (default: 'ui').
- Provide explicit label/ariaLabel for business-specific wording.
- Use component inputs like uploadText/uploadHint when you want local override.
- Verify language switch in runtime (EN <-> PL) on at least one form page.

## Related pages

- Getting Started: Project bootstrap and first component setup. (/docs/getting-started)
- Installation: Environment requirements and package setup. (/docs/installation)