Skip to main content

turkmen-translit

Convert Turkmen text between the legacy Cyrillic alphabet and the current official Latin alphabet — correctly, including the letters other tools get wrong.

CI License: MIT Python 3.9+ Zero dependencies

Turkmenistan's official script is the Latin alphabet (30 letters). A lot of older text — books, documents, websites — is still in the 1940–1993 Cyrillic alphabet. This converts between them from the command line or from Python, with no dependencies, and with the tricky letters handled explicitly rather than guessed.

$ tr-tm "Түркменистан"
Türkmenistan
$ tr-tm "Aşgabat"
Ашгабат
$ tr-tm --detect "salam"
latin

Why this exists

Most quick transliterators get the same handful of Turkmen letters wrong, because they borrow a Russian or Turkish table:

  • Ж → ž (the /ʒ/ sound) and Җ → j (the /dʒ/ sound) are two different Cyrillic letters. Tools that map both to j (or both to zh) corrupt words.
  • В → w, not v.
  • Й → ý, Ы → y, И → i — and Turkmen does not use the Turkish dotless ı.

This library encodes the full 30-letter correspondence from the Wikipedia Turkmen alphabet table, cross-checked against the BGN/PCGN 2000 romanization, and documents every edge case in docs/orthography.md.

Install

pipx install turkmen-translit     # for the tr-tm command
# or
pip install turkmen-translit      # for the library

Python 3.9+, no third-party dependencies.

JavaScript / TypeScript: the same tables are available as an npm package for Node and the browser — see js/:

npm install @garag0l/turkmen-translit

Command line

tr-tm "Түркменистан"              # auto-detect script, convert to the other one
tr-tm --to-latin "Ашгабат"        # force Cyrillic -> Latin
tr-tm --to-cyrillic "Aşgabat"     # force Latin -> Cyrillic (best effort)
tr-tm --detect "salam"            # just report: cyrillic | latin | mixed | unknown
echo "salam" | tr-tm              # read stdin
tr-tm -i book.txt -o book-latin.txt   # whole files, UTF-8

Python

from turkmen_translit import cyrillic_to_latin, latin_to_cyrillic, detect_script

cyrillic_to_latin("Түркменистан")  # 'Türkmenistan'
latin_to_cyrillic("Aşgabat")  # 'Ашгабат'
detect_script("salam")  # 'latin'

Characters outside the alphabet (ASCII, digits, punctuation, whitespace, other scripts) pass through unchanged. Capitalisation is preserved, including all-caps words with the multi-letter glides (ЯН → ÝAN, Яз → Ýaz).

Which direction is reliable?

Cyrillic → Latin is the authoritative direction — converting legacy text to the current official script. Every core letter is 1:1.

Latin → Cyrillic is a documented best-effort. The modern Latin script merged some distinctions the old Cyrillic kept, so the reverse can't always be exact:

  • The 30 core letters invert exactly: salam ↔ салам.
  • The glide letter ý goes back to Й, never guessed into Я/Ё/Ю: ýa → йа.
  • Letters that are dropped one way (hard/soft sign) don't come back.

Full rules and rationale: docs/orthography.md. If you find a word that converts wrong, open an issue with the word and the expected result.

Tested

  • Every one of the 30 core letters round-trips Cyrillic → Latin → Cyrillic, upper and lower case.
  • The letters tools most often get wrong (Ж/Җ, Й, Ң, Ә, В, Ы) are pinned by explicit assertions.
  • Known words (Türkmenistan, Aşgabat, salam), capitalisation of the glide letters, passthrough, the documented lossy cases, and the CLI (stdin, files, flags) all have tests.
  • CI runs on Linux/macOS/Windows across Python 3.9–3.13.

Roadmap

  • A JavaScript/TypeScript port sharing these exact tables. Shipped — see js/.
  • Optional Е/Э disambiguation heuristics for the reverse direction.

Contributing

Issues and PRs welcome — especially real Turkmen words that transliterate wrong, with a source for the correct spelling.

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest && ruff check .

License

MIT. Built by Murat Bekgi.

Metadata

Release files for turkmen-translit 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for turkmen-translit 0.1.1
File Size Uploaded Provenance Actions
turkmen_translit-0.1.1.tar.gz 18.8 kB With provenance Details for turkmen_translit-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for turkmen-translit 0.1.1
File Interpreter ABI Platform Actions
turkmen_translit-0.1.1-py3-none-any.whl Python 3 none any Details for turkmen_translit-0.1.1-py3-none-any.whl

Total release size: 29.4 kB

Release files / turkmen_translit-0.1.1.tar.gz

Download URL turkmen_translit-0.1.1.tar.gz
Size 18.8 kB
Tags Source
SHA-256 checksum
How to use checksums
bd81931a56fe5e4299143ad851b115fa8a1310e57be34dc705d5085839c0bccf
BLAKE2b-256 checksum
How to use checksums
43daa8c85c4a8db2eaaeac4201dd313b483e9acbf1f823415fe0095f8423631a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / turkmen_translit-0.1.1-py3-none-any.whl

Download URL turkmen_translit-0.1.1-py3-none-any.whl
Size 10.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f9f9a73ef4c644e6f19939e717a10cb1b9591bf8ec18e4eba63791475b60d67c
BLAKE2b-256 checksum
How to use checksums
e281ce9b1c8999a059259c4d5f1456aea45869ee49d88ed1a9e02e3a564e2cdb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for turkmen-translit 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for turkmen_translit-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page