Localization

Nmbr supports English and French, so admins and employees can each work in the language they prefer, even when those preferences differ within a single employer.

API response language

A response can contain user-facing text, such as a validation message. Send an Accept-Language header to choose its language.

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employees \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Accept-Language: fr' \
     --header 'content-type: application/json' \
     --data '{ "first_name": "Kendall", "last_name": "Tremblay", "sin": "123456789" }'

Nmbr matches the header against the locales it supports and applies the best match. Every response carries a Content-Language header telling you which locale was used.

Content-Language: fr

Supported locales are en and fr. A request with no Accept-Language header, or one naming a locale Nmbr does not support, is answered in English. The header changes two things: the messages Nmbr generates, and which translation is returned for translatable attributes. Response

{
  "message": "Le numéro d'assurance sociale est correctement formaté, mais n'est pas un NAS valide.",
  "errors": {
    "sin": [
      "Le numéro d'assurance sociale est correctement formaté, mais n'est pas un NAS valide."
    ]
  }
}

Field names, object types, warning types, and identifiers are the same in every locale. Only the human-readable message text changes. See Payroll Data Requirements.

Translatable attributes

Some values are customer-generated, such as a pay rate’s title. These values can carry a translation for each supported locale, and Nmbr returns the one matching the request. title, label, name, and description are translatable where an endpoint offers them. Check the API reference for the endpoint you are working with. Where an attribute is translatable, it appears three times in a response. Taking title on a pay rate as the example:

Field	Type	Writable
`title`	string	Yes
`title_translations`	object keyed by locale	Yes
`title_translated`	string	No

title is the default, used when no translation matches the requested locale. title_translations holds a translation per locale. title_translated is resolved for you: Nmbr returns the translation matching the request locale, and falls back to title when there is none. Request

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/pay_rates \
     --header 'Authorization: Bearer <access_token>' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "title": "Weekend rate",
        "title_translations": {
          "fr": "Taux de fin de semaine"
        }
     }'

Response with Accept-Language: fr

{
  "title": "Weekend rate",
  "title_translations": {
    "fr": "Taux de fin de semaine"
  },
  "title_translated": "Taux de fin de semaine"
}

The same record requested with Accept-Language: en, or with no header, returns "title_translated": "Weekend rate". There is no en translation, so title is used. title and title_translations are independent, so set a translation only for the locales you care about. A locale present in title_translations does not have to match title, and you do not need an entry for the language title happens to be written in. Nmbr never derives one language from another: title_translated only ever returns a value you supplied, or title.

Writing translations

Send the _translations object with a key for each locale you want to set. You do not have to supply every locale. Any locale you leave out falls back to the base attribute when read. Nmbr rejects a _translations value that is not an object, contains a key that is not a supported locale, or has an empty or non-string value for any locale. Sending _translations replaces the whole set. To remove a locale, send the object again without that locale. To clear every translation, send null. Some translatable attributes are read-only Nmbr reference data rather than text you own. They follow the same three-field shape, and Nmbr supplies the translations. Response from a bank account lookup, with Accept-Language: fr

{
  "institution_name": "Royal Bank of Canada",
  "institution_name_translations": {
    "en": "Royal Bank of Canada",
    "fr": "Banque Royale du Canada"
  },
  "institution_name_translated": "Banque Royale du Canada"
}

Payee communications

A payee receives communications from Nmbr, such as pay stub emails and year-end forms, and each needs to be in their preferred language. That language comes from a stored setting, preferred_locale.

Locale inheritance

Set preferred_locale at the level you want it to apply. Any level you leave unset inherits from the one above it. With nothing set at any level, communications default to English.

Set it on	Applies to	When to set it
Your partner account	Everything below, unless overridden	A single default language for the whole account
A company	That company, its business entities, and its payees	A company operates in a different language from your default
An employee or contractor	That person	One person needs a different language from their company
A business entity	That business entity	Rarely: payees inherit from the company, not the entity (see below)

Setting it on a business entity does not change the language for payees working there. Payees inherit from the company, because one person can hold work assignments at more than one business entity.

A change takes effect immediately for everything below it that has no setting of its own, with no confirmation step. Switching your partner account from English to French means every company, business entity, and payee relying on that default starts receiving communications in French, including employees who have been getting English pay stubs until now.

Sending Accept-Language: fr does not change what an employee receives in their inbox. Setting preferred_locale to fr does not change the language of your API responses.

Overview

Bulk & Batch Operations

Partner

Companies

Employees

Contractors

Payrolls

Line Items

Banking

Reporting

Forms

Vacation Pay

Lookups

Calculations

Miscellaneous

Localization

API response language

Translatable attributes

Writing translations

Payee communications

Locale inheritance

​API response language

​Translatable attributes

​Writing translations

​Payee communications

​Locale inheritance

API response language

Translatable attributes

Writing translations

Payee communications

Locale inheritance