Internationalization (i18n)

VerifyKit includes a lightweight translation system for UI strings. You can switch locales, override specific strings, or register entirely new locales.

API Overview

The i18n module exports the following functions:

Function	Description
`t(key, locale?)`	Translate a key. Falls back to English, then to the key itself.
`setLocale(locale)`	Set the active locale globally.
`getLocale()`	Get the current active locale code.
`registerLocale(locale, strings)`	Register a new locale or add overrides to an existing one.
`getAvailableLocales()`	Get an array of all registered locale codes.

typescript

import { t, setLocale, getLocale, registerLocale, getAvailableLocales } from '@trexolab/verifykit-react'

The following types are also exported:

typescript

import type { Locale, TranslationStrings } from '@trexolab/verifykit-react'

Locale is typed as 'en' | 'fr' | 'de' | 'es' | 'ar' | 'ja' | 'zh' | string, allowing both built-in and custom locale codes.

The default locale is 'en' (English). All built-in UI components use t() to resolve their display strings. If a key is not found in the current locale, the system falls back to the English translation, then to the raw key string.

Translation Keys

The TranslationStrings interface defines all translatable keys. Below is the complete list with their default English values.

Key	Default (English)
`toolbar.openFile`	Open file
`toolbar.previousPage`	Previous page
`toolbar.nextPage`	Next page
`toolbar.zoomIn`	Zoom in
`toolbar.zoomOut`	Zoom out
`toolbar.fitWidth`	Fit width
`toolbar.fitPage`	Fit page
`toolbar.rotateClockwise`	Rotate clockwise
`toolbar.rotateCounterclockwise`	Rotate counterclockwise
`toolbar.search`	Search
`toolbar.print`	Print
`toolbar.download`	Download
`toolbar.theme`	Toggle theme
`toolbar.fullscreen`	Fullscreen
`toolbar.signatures`	Signatures
`toolbar.moreOptions`	More options

Status Messages

Key	Default (English)
`status.valid`	Valid
`status.invalid`	Invalid
`status.warning`	Warning
`status.unknown`	Unknown
`status.pending`	Pending

Signature Panel

Key	Default (English)
`panel.signatures`	Signatures
`panel.noSignatures`	No signatures found
`panel.unsignedFields`	Unsigned signature fields
`panel.signerCertificate`	Signer Certificate
`panel.certificateChain`	Certificate Chain
`panel.viewProperties`	View Properties

Document

Key	Default (English)
`document.properties`	Document Properties
`document.metadata`	Metadata

Find Bar

Key	Default (English)
`find.placeholder`	Find in document...
`find.noResults`	No results found
`find.matchCase`	Match case
`find.wholeWords`	Whole words

Welcome Screen

Key	Default (English)
`welcome.title`	Open a PDF document
`welcome.subtitle`	Drag & drop a file here, or click to browse
`welcome.dropHint`	Drop PDF file here

Password Dialog

Key	Default (English)
`password.title`	Password Required
`password.placeholder`	Enter password
`password.submit`	Open
`password.incorrect`	Incorrect password. Please try again.

Verification

Key	Default (English)
`verification.checking`	Verifying signatures...
`verification.complete`	Verification complete

PAdES Levels

Key	Default (English)
`pades.B-B`	PAdES B-B (Basic)
`pades.B-T`	PAdES B-T (Timestamp)
`pades.B-LT`	PAdES B-LT (Long-Term)
`pades.B-LTA`	PAdES B-LTA (Long-Term Archival)

General

Key	Default (English)
`general.close`	Close
`general.cancel`	Cancel
`general.ok`	OK
`general.loading`	Loading...
`general.error`	Error

The TranslationStrings interface also includes an index signature ([key: string]: string), allowing you to add custom keys beyond those listed above.

Using with VerifyKitProvider

The VerifyKitProvider accepts locale and translations in its config:

tsx

<VerifyKitProvider config={{
  workerUrl: '/pdf.worker.min.mjs',
  locale: 'fr',
  translations: {
    'toolbar.search': 'Rechercher',
    'panel.noSignatures': 'Aucune signature trouvée',
  },
}}>
  <App />
</VerifyKitProvider>

locale sets the active locale when the provider mounts.
translations registers partial overrides for the specified locale. If locale is 'fr', the translations are merged into the 'fr' locale.

Switching Locale at Runtime

Use setLocale() to change the active locale. Components that call t() during render will pick up the new locale on the next render cycle.

typescript

import { setLocale, getLocale } from '@trexolab/verifykit-react'
 
// Check current locale
console.log(getLocale()) // 'en'
 
// Switch to French
setLocale('fr')
console.log(getLocale()) // 'fr'

Note: setLocale() changes a module-level variable. It does not trigger a React re-render on its own. If you need the UI to update immediately, trigger a re-render in your application (e.g., via state change).

Adding a Custom Locale

Use registerLocale() to add a complete locale or extend an existing one:

typescript

import { registerLocale, setLocale } from '@trexolab/verifykit-react'
 
// Register a full Portuguese locale
registerLocale('pt', {
  'toolbar.openFile': 'Abrir arquivo',
  'toolbar.previousPage': 'Pagina anterior',
  'toolbar.nextPage': 'Proxima pagina',
  'toolbar.zoomIn': 'Ampliar',
  'toolbar.zoomOut': 'Reduzir',
  'toolbar.search': 'Pesquisar',
  'toolbar.print': 'Imprimir',
  'toolbar.download': 'Baixar',
  'status.valid': 'Valido',
  'status.invalid': 'Invalido',
  'status.unknown': 'Desconhecido',
  'panel.signatures': 'Assinaturas',
  'panel.noSignatures': 'Nenhuma assinatura encontrada',
  'welcome.title': 'Abra um documento PDF',
  'welcome.subtitle': 'Arraste e solte um arquivo aqui, ou clique para navegar',
  'general.close': 'Fechar',
  'general.cancel': 'Cancelar',
  'general.ok': 'OK',
})
 
// Activate it
setLocale('pt')

Any keys not provided in your custom locale will fall back to the English default.

Overriding Specific Strings

You can override individual strings without creating a full locale. This is useful for branding or terminology adjustments:

typescript

import { registerLocale } from '@trexolab/verifykit-react'
 
// Override just a few English strings
registerLocale('en', {
  'welcome.title': 'Upload your document',
  'welcome.subtitle': 'Drop a signed PDF here to verify its signatures',
})

Calling registerLocale() on an existing locale merges the new strings with the existing ones. Existing strings that are not included in the override are preserved.

Listing Available Locales

typescript

import { getAvailableLocales } from '@trexolab/verifykit-react'
 
console.log(getAvailableLocales()) // ['en']
 
// After registering custom locales:
registerLocale('fr', { 'general.ok': 'OK' })
registerLocale('de', { 'general.ok': 'OK' })
console.log(getAvailableLocales()) // ['en', 'fr', 'de']

Using t() Directly

The t() function can be used outside of React components for headless or utility code:

typescript

import { t, setLocale } from '@trexolab/verifykit-react'
 
setLocale('en')
console.log(t('status.valid'))   // 'Valid'
console.log(t('status.invalid')) // 'Invalid'
 
// Override per-call without changing the global locale
console.log(t('status.valid', 'fr')) // Uses French if registered, else falls back to English

The fallback chain is:

The requested locale's value for the key
The English ('en') value for the key
The raw key string itself