utm-translit

Build clean UTM-tagged URLs with automatic Cyrillic → Latin transliteration and value normalization. Zero dependencies. Works in Node.js and the browser.

Marketers who run ads in CIS markets hit the same problem: Cyrillic values in UTM tags get percent-encoded into unreadable junk (utm_campaign=%D0%90%D0%BA%D1%86%D0%B8%D1%8F), inflating reports with duplicate channels. utm-translit solves it the way the free online UTM generator at nepolyakov.ru does — transliterate, lowercase, strip unsafe characters, and assemble a clean link.

This package is the open-source core of that tool. Prefer a no-install UI? Use the live UTM generator.

Why

• Clean analytics data. Летняя Акция → letnyaya_akciya, not %D0%9B....
• No duplicate channels. Forces lowercase, because CPC and cpc are two different sources in Yandex.Metrica / GA4.
• Safe by default. Spaces → _, unsafe chars removed, dynamic placeholders like {campaign_id} and {keyword} preserved.
• Tiny. Zero dependencies, ~3 KB, runs anywhere URL exists.

Install

npm install utm-translit

Usage

const { buildUtm, cleanValue, preset } = require('utm-translit');
// ESM: import { buildUtm } from 'utm-translit';

buildUtm('example.com', {
  source: 'yandex',
  medium: 'cpc',
  campaign: 'Летняя Акция',
});
// → https://example.com/?utm_source=yandex&utm_medium=cpc&utm_campaign=letnyaya_aktsiya

// Presets for common channels
buildUtm('https://shop.ru/sale', { ...preset('yandex'), campaign: 'summer' });
// → https://shop.ru/sale?utm_source=yandex&utm_medium=cpc&utm_campaign=summer&utm_term={keyword}

// Just normalize a single value
cleanValue('Чёрная Пятница'); // → 'chyornaya_pyatnitsa'

Options

buildUtm(url, params, {
  translit: true,   // transliterate Cyrillic (default true)
  lowercase: true,  // force lowercase (default true)
  decode: true,     // human-readable output (default true)
});

Presets

yandex, google, vk, telegram, email — see PRESETS.

CLI

npx utm-translit example.com -s yandex -m cpc -c "Летняя Акция"
# → https://example.com/?utm_source=yandex&utm_medium=cpc&utm_campaign=letnyaya_aktsiya

npx utm-translit example.com --preset yandex --campaign summer_sale

Run npx utm-translit --help for all flags.

Browser

<script type="module">
  import { buildUtm } from 'https://unpkg.com/utm-translit/src/index.mjs';
  console.log(buildUtm('example.com', { source: 'telegram', medium: 'social' }));
</script>

API

| Function | Description | | --- | --- | | buildUtm(url, params?, options?) | Assemble a UTM-tagged URL. Preserves existing query params, adds https:// if missing, skips empty values. | | cleanValue(str, options?) | Normalize one value: lowercase → transliterate → strip unsafe chars. | | preset(name) | Get a mutable copy of a channel preset. |

Transliteration standard

The mapping follows the same marketing-oriented standard used by the UTM link standard guide (ё → yo, ж → zh, х → kh, ц → ts, щ → sch, …). Soft/hard signs are dropped.

Related

• Free online UTM generator — the no-code web version of this library.
• Marketing engineering tools — ROMI, ER, schema.org and llms.txt generators by the same author.
• About the author — Nikolai Polyakov, performance marketing & analytics.

License

MIT © Nikolai Polyakov