Skip to main content

Client API

All methods are available on the global Loco object after loading loco.js.

Loco.init(config)​

Initialize Loco. Must be called before any other method.

// Server mode
Loco.init({
  apiUrl: 'https://your-loco-server.com',  // required
  apiKey: 'YOUR_24_CHAR_API_KEY',           // required
});

// File mode — single file
Loco.init({ file: '/translations.json' });

// File mode — multiple files (merged; later files win key conflicts)
Loco.init({ files: ['/translations-core.json', '/translations-extra.json'] });

// File mode — high-priority override file (merges last regardless of position)
Loco.init({
  files: [
    '/translations-core.json',
    { url: '/client-overrides.json', priority: 100 }
  ]
});

Loco.apply(lang) → Promise​

Fetch and apply translations for a language. Swaps all discovered text in the DOM. Returns a Promise.

await Loco.apply('fr');
// resolves with: { applied: 142, skipped: 3 }

Loco.restore()​

Revert all translated text back to the original.

Loco.restore();

Loco.rescan() → Promise​

Force a re-scan of the DOM for newly added text nodes and register them with the server.

await Loco.rescan();

Loco.languages() → Promise​

Get the list of available languages for the current project.

const langs = await Loco.languages();
// [{ code: 'fr', name: 'Français' }, { code: 'zh-CN', name: 'Simplified Chinese' }]

Loco.widget(options)​

Render a floating language switcher widget.

Loco.widget({ position: 'bottom-right' });
// positions: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'

Loco.textnodes()​

Return all phrases discovered on the current page.

const phrases = Loco.textnodes();
// [
//   { key: 'Hello', context: 'Login > Box', element: <span> },
//   { key: 'You have {{number:0}} tasks', context: 'Dashboard > Header', element: <p> }
// ]

Each entry:

  • key — extracted text or slot pattern (e.g. "Hello {{text:0}}")
  • context — DOM context trace (e.g. "Dashboard > Header")
  • element — live DOM reference

Loco.stopScan()​

Pause the MutationObserver. New DOM nodes will not be registered.

Loco.startScan()​

Resume the MutationObserver.

Loco.isFileMode() → boolean​

Returns true if Loco was initialized in file mode.

if (Loco.isFileMode()) {
  // No server connection available
}

Loco.clearCache() → Promise (file mode only)​

Clear the IndexedDB translation cache and the saved language preference.

await Loco.clearCache();

Loco.addFile(url) → Promise (file mode only)​

Load and merge an additional translation file at runtime.

const result = await Loco.addFile('/translations-extra.json');

Loco.pullLatest() → Promise (file mode only)​

Re-fetch translation files from the network if the server has a newer timestamp than what is cached in IndexedDB.

const result = await Loco.pullLatest();
// { status: 'updated' } | { status: 'fresh' }