Scope

Currently the possibilities for internationalization, e.g. translation of wordings, is quite limited.

Only p-pagination and p-carousel offer something via their intl prop.
Some other components provide the aria prop where an aria-label can be set.

Others, like p-modal and p-inline-notification don't offer any possibility to translate their dismiss buttons.
As brought up here, p-pagination's intl isn't flexible enough to allow correct wordings/aria-labels for other languages like they are used in Japan, Korea and Latvia, where the page number would be in the middle of two characters/words like 第2頁.

Let's come up with a solution that works for all components.

Notes

• Articles:
  • https://dev.to/btopro/i18n-in-web-components-2gii (kind of irrelevant since this from an application's perspective)
  • https://dev.to/teamhive/using-i18n-translations-within-stencil-components-4n30 (same here)
• Community:
  • https://porschedev.slack.com/archives/CT7AVHTTQ/p1687356357040689
  • https://porschedev.slack.com/archives/CT7AVHTTQ/p1704281968618189
• TODOs:
  • Shall we offer already translated PDS components or just the interface, so that the consumer have to translate it
  • Create concept of how intl, aria and sr-only texts work together.
  • Does it make sense to provide a translation list on provider level?
  • How do teams (finder, shop, configurator, my porsche, pcom) do translations?
  • p-pagination could be solved via magic strings or substitution patterns like 第%s頁 or alternatively with a callback like page?: string | (pageIndex: number) => string;

Acceptance criteria

• A proposal is worked out on how PDS components support standardized internationalization

Subtasks

• research framework i18n solutions
  • https://angular.io/guide/i18n-example
  • https://ngneat.github.io/transloco/
  • https://www.i18next.com/ with https://react.i18next.com/ and https://github.com/Romanchuk/angular-i18next and more https://www.i18next.com/overview/supported-frameworks
  • https://github.com/ngx-translate/core seems dead
  • https://vue-i18n.intlify.dev/
• overview of i18n components
• difference intl and a11y prop and future translations ––> intl and a11y currently control aria labels, nothing visual
• draft i18n example
• ask various teams about their i18n library
  • Porsche ID: @ngx-translate/core with PhraseApp
  • My Porsche: @ngx-translate/core and ngx-translate-messageformat-compiler
  • Shopfront: next-intl and react-intl with PhraseApp
  • Finder: @formatjs/intl on server, react-intl on client

Results

• consumer should be able to change translations since
  • even if we could cover all relevant languages there might still be need to customize
  • add another language/dialect
  • lazy loading translations
• local overrides on per component level should be possible
• global defaults possible to set via provider/module
• interpolation via {{value}} seems to be supported by most i18n libraries except vue which uses {value} which could be handled with a replacement on provider level which would be good for consistency from a team's or translator's perspective
• tools for translating
  • https://phrase.com/de/
  • https://weblate.org/de/
  • https://locize.com/
• components with wordings (see component-meta for a list of extracted wordings)
  • p-flyout
  • p-flyout-navigation
  • p-flyout-navigation-item
  • p-inline-notification
  • p-modal
  • p-multi-select
  • p-popover
  • p-select-wrapper-dropdown
  • p-text-field-wrapper
  • p-toast-item
  • p-wordmark
  • keep in mind parent component might need to forward it, e.g. p-banner using p-inline-notification internally
• components with intl prop
  • p-carousel (Override the default wordings that are used for aria-labels on the next/prev buttons and pagination.)

{
  prev: 'string', 
  next: 'string',
  first: 'string',
  last: 'string',
  slideLabel: 'string',
  slide: 'string',
}

• p-pagination (Override the default wordings that are used for aria-labels on the next/prev and page buttons.)

{
  root: 'string',
  prev: 'string',
  next: 'string',
  page: 'string',
}

• components with aria prop
  • p-button
  • p-button-pure
  • p-button-tile
  • p-carousel
  • p-crest
  • p-flyout
  • p-flyout-navigation
  • p-icon
  • p-link
  • p-link-pure
  • p-link-tile
  • p-marque
  • p-modal
  • p-pagination
  • p-popover
  • p-scroller
  • p-spinner
  • p-tag-dismissible
  • p-wordmark

Questions

• singular/plural handling relevant? ––> not so far and kind of unlikely for atomic components
• bundling in core chunk vs component chunks? ––> irrelevant since handled on application level
• interpolation (= merging translations with variables) with multiple values? ––> currently not relevant for the extracted wordings, but seems required for p-pagination's intl prop, e.g. 第2頁 which would easily be possible via {{value}} replacement, however more tricky for more than one value (see i18n libraries above for possible solutions)

Conclusion

• intl and aria prop have some overlap since both are only relevant for aria-* attributes and should probably be merged together since it is somewhat confusing
• this is somewhat different from the "hidden" wordings that we want to customize here, so introducing a new prop translations or wordings (probably better since this is what the prop supplies, not a translation for different languages/locales)
• we still need the current default as a fallback, in case of someone trying to customize it with ""
• ideally we introduce a components prop on PorscheDesignSystemProvider and option on PorscheDesignSystemModule where the default values for props can be configured for each component (for now, maybe just for translations or wordings or whatever we want to call it)
• components that don't have a configurable prop, should not show up
• this allows global or per module configuration with local overrides where needed
• consuming teams then need to either specify the wordings on a per component basis (or wrap it in their own component) or map their wordings to our config, this way we are compatible with plain html and frameworks no matter which i18n library
• ideally all wordings should be extracted and have their customizability be verified via component-meta and documented/explained
• drafted example for p-inline-notification and react: https://github.com/porsche-design-system/porsche-design-system/pull/3004/files

Final Conclusion

• intl prop gets deprecated
• we don't add a new translations or wordings prop
• we add/extend aria props since currently all values affect screen readers only
• draft for p-pagination

  /**
   * @deprecated since v3.10.0 use `aria` instead
   * Override the default wordings that are used for aria-labels on the next/prev and page buttons. */
  @Prop() public intl?: PaginationInternationalization = {
    root: 'Pagination',
    prev: 'Previous page',
    next: 'Next page',
    page: 'Page',
  };

  @Prop() public aria?: SelectedAriaAttributes<'aria-label'> & {
    prev: SelectedAriaAttributes<'aria-label'>;
    next: SelectedAriaAttributes<'aria-label'>;
    page: SelectedAriaAttributes<'aria-label'>;
  } = {
    'aria-label': 'Pagination',
    prev: { 'aria-label': 'Previous page' },
    next: { 'aria-label': 'Next page' },
    page: { 'aria-label': 'Page' },
  };

• also check components like p-button that have a nested p-spinner with a hard coded aria={{ 'aria-label': 'Loading state' }} which currently is not extracted
• follow-up ticket: Support for internationalization (i18n) #3015