@nextcloud/l10n

@nextcloud/l10n

Nextcloud L10n helpers for apps and libraries.

Installation

npm i -S @nextcloud/l10n

Usage

OC.L10n abstraction

You can use helpers in this package in order generate code that also works when it's not loaded on a Nextcloud page. This is primary useful for testing. The logic will just return the original string if the global variable OC isn't found.

In order to not break the l10n string extraction scripts, make sure to alias the imported function to match the legacy syntax:

import { t, n } from '@nextcloud/l10n'
// Or
import { translate as t, translatePlural as n } from '@nextcloud/l10n'

t('myapp', 'Hello!')
n('myapp', '%n cloud', '%n clouds', 100)

See the localization docs for more info.

Independent translation

You can use this package to translate your app or library independent of Nextcloud. For that you need .po(t) files. These can be extracted with gettext-extractor.

import { getGettextBuilder } from '@nextcloud/l10n/gettext'

const lang = 'sv'
const po = ... // Use https://github.com/smhg/gettext-parser to read and convert your .po(t) file

const gt = getGettextBuilder()
    .detectLocale()
    .addTranslation('sv', po)
    .build()

Translate single string

gt.gettext('my source string')

Placeholders

gt.gettext('this is a {placeholder}. and this is {key2}', {
    placeholder: 'test',
    key2: 'also a test',
})

See the developer docs for general guidelines.

Translate plurals

gt.ngettext('%n Mississippi', '%n Mississippi', 3)

See the developer docs for general guidelines.

Changelog

3.1.0 - 2024-05-07

Added

• Allow setting escape option per parameter replacing.
  For more security this should be used instead of disabling paramter escaping, see pull request #756

  // Example
  t(
  	'my-app',
  	'{a}{userInput}{a_end}',
  	{
  		a: {
  			value: '<a>',
  			escape: false,
  		},
  		userInput: somePossiblyInsecureValue, // This will be escaped
  		a_end: {
  			value: '</a>',
  			escape: false,
  		}
  	},
  )