Internationalization

@gitlab/ui ships with built-in US English strings for every label it renders internally (pagination controls, close buttons, search placeholders, and so on). When your application is internationalized, you must supply translated versions of those strings so that no untranslated English text leaks into your UI.

This page explains how to configure @gitlab/ui with your application's translations and how to override individual component labels in context.

How it works

Every component label that @gitlab/ui renders is registered under a translation key — a dot-separated string such as GlPagination.labelNextPage. At startup, you provide a translations map that pairs each key with a translated string (or a pluralization function). From that point on, every instance of the component uses your translation automatically.

The full list of translation keys and their default US English values is in the All translation keys section below.

Configure translations at startup

Call setConfigs once, before any @gitlab/ui component is mounted. In production, any subsequent call is silently ignored. In development, it throws an error to alert you to the duplicate call.

import setConfigs from '@gitlab/ui/src/config';

setConfigs({
  translations: {
    'GlAlert.closeButtonTitle': __('Dismiss'),
    'GlModal.closeButtonTitle': __('Close'),
    'GlPagination.nav': __('Pagination'),
    'GlPagination.labelFirstPage': __('Go to first page'),
    'GlPagination.labelLastPage': __('Go to last page'),
    'GlPagination.labelNextPage': __('Go to next page'),
    'GlPagination.labelPrevPage': __('Go to previous page'),
    'GlPagination.labelPage': __('Go to page %{page}'),
    // … all other keys
  },
});

Replace __() with your application's translation function (for example, i18n.t(), gettextCatalog.getString(), or any other i18n helper).

Other configuration options

setConfigs also accepts two additional options unrelated to translations:

Option	Type	Default	Description
`firstDayOfWeek`	Number (0-6)	`0` (Sunday)	Sets the first day of the week in date pickers. `0` = Sunday, `1` = Monday, …, `6` = Saturday.
`accessibleDisabledButton`	Boolean	`false`	Opt-in flag that renders disabled buttons with `aria-disabled` instead of the native `disabled` attribute, preserving keyboard focus and tooltip visibility.

setConfigs({
  firstDayOfWeek: 1, // Monday
  accessibleDisabledButton: true,
  translations: { /* … */ },
});

Parameterized labels

Some labels contain named placeholders such as %{page} or %{label}. Pass the translated string with the same placeholder intact; @gitlab/ui substitutes the value at render time using its built-in sprintf helper.

'GlPagination.labelPage': __('Go to page %{page}'),
'GlLabel.removeButtonAriaLabel': __('Remove label - %{label}'),

Pluralized labels

Labels that vary by count use a function value instead of a string. The function receives the count as its only argument and must return the correct plural form for that count.

// Using GitLab's n__() helper (follows Unicode CLDR plural rules):
'GlCollapsibleListbox.srOnlyResultsLabel': (n) => n__('%d result', '%d results', n),

Using n__() (or an equivalent CLDR-aware helper) is required for correct plural forms in languages where the singular category is not equivalent to the number 1 (for example, French, Ukrainian, and Arabic).

Override a label in context

When a single component instance needs a different string — for example, a search input whose placeholder must match the specific resource being searched — pass the label directly as a prop. Prop values always take precedence over the generic translation.

<gl-search-box-by-type
  :placeholder="__('Search merge requests')"
  :clear-button-title="__('Clear search')"
/>

Refer to each component's API documentation for the exact prop names that correspond to its translatable labels.

Development warnings

In development (NODE_ENV === 'development'), @gitlab/ui logs a console warning listing any translation keys that were not supplied to setConfigs. Use this output to ensure your translations map is complete before shipping.

Translation key stability

Translation keys are considered part of the public API. A key change is a breaking change: if a key is renamed, any translation you registered under the old name stops being applied. Watch the GitLab UI changelog for key changes when upgrading.

All translation keys

The canonical, always-current list of every key and its default US English value is packages/gitlab-ui/translations.js in the Pajamas repository. That file is updated automatically by yarn translations:collect whenever a new translatable label is added to @gitlab/ui, so it is always in sync with the installed version of the library.