A Windows/Excel VBA tool that prepares Adyghe (ady) and Kabardian (kbd) sentence collections for submission to the Mozilla Common Voice project: it classifies sentences by topic, exports them as clean UTF-8 .txt files, and validates and transliterates them using a built-in VBA engine ported from circassian-transliterate (circ.py). No Python installation is required.
| Design & Development | nemerko |
| Excel Workbook Version | 2.3.0 |
| VBA Application Version | 2.1.0 |
| Release Date | 2026-08-15 |
| License | NEMERKO Limited Open License (NLO License) v2.0 — source-available; non-commercial use free, derivatives and commercial use by permission |
| Platform | Windows + Microsoft Excel 2021 or newer (VBA) |
The workbook (sheets,
LUT, templates, sample data) and the VBA application (the form and its macros) are versioned separately. The file name (MCV-ady-kbd-txt-creator.xlsm) stays stable across releases; the current workbook version is recorded in theINFOsheet's own "File Version History" table, and the Version History below tracks the VBA application.
- Description
- Why this tool exists
- Features
- Requirements
- Installation & First-Time Setup
- Workbook Structure
- Usage
- Output File Formats
- Domain (Field) Codes Reference
- Troubleshooting
- Credits
- License
- Version History
TXT File Creator & Validator is a VBA application designed to classify Adyghe and Kabardian (Circassian languages) sentences into topics, save them in .txt format with UTF-8 encoding, validate these files, compute statistics, and perform Turkish-letter transliteration efficiently and error-free.
Unlike other, more common languages, preparing and submitting Adyghe and Kabardian sentences directly through the Mozilla Common Voice web portal can run into a range of problems: unsupported or inconsistent characters, spelling variation, and the fact that most native speakers of these endangered languages are not literate in them.
With this tool, sentences are first collected in an Excel workbook, tagged by topic, and then classified, checked, and packaged for bulk upload to MCV — quickly and without manual errors. It provides:
- Pre-submission validation of sentences against MCV's formatting rules.
- Automatic classification of sentences by topic/domain.
- Correction of invalid characters.
- Sentence, word, and character statistics.
- ady → tr and kbd → tr transliteration.
All of this is exposed through a single interactive form — no coding knowledge required to operate it day-to-day.
- Bulk-converts a prepared Excel sentence list into UTF-8
.txtfiles sized to MCV's per-file sentence limit. - Automatically groups sentences by language (ady/kbd), regional variant, and domain code (since v1.2.0).
- One-click statistics: total files, total sentences, total groups, min/max/average sentences per file and per group.
- Built-in VBA engine (ported from
circassian-transliterate/circ.py) validates, generates stats for, and transliterates the generated files without leaving Excel — no Python installation needed. - Adjustable validation thresholds (min/max sentence length, min/max word count).
On the relationship with
circ.py: the VBA engine originated as a port ofcirc.py. The port itself, and the byte-for-byte comparison made against the original script at the time, are described in the v2.0.0 release.
- Windows 10/11 — the tool uses the Windows folder picker and
ADODB.Stream, so it will not run in Excel for Mac or Excel Online. - Microsoft Excel 2021 or newer (or Microsoft 365 desktop) with macros enabled.
- The ADODB (Microsoft ActiveX Data Objects) component, used internally to read/write UTF-8 text files. This ships with Windows/Office by default; no manual VBA reference needs to be added, since the workbook creates it via late binding (
CreateObject("ADODB.Stream")).
No Python installation and no external circ.py file are required — validation, transliteration, and statistics all run natively inside the workbook's VBA project.
- Download or clone this repository.
- Open
MCV-ady-kbd-txt-creator.xlsmin Excel. - If Excel shows a security warning bar, click Enable Content to allow the macros to run. (If the file was downloaded from the internet, you may first need to right-click it → Properties → Unblock.)
That's it — no separate interpreter or external tool to install.
Reading the VBA source. The VBA project is protected with the password
1. The lock is there to stop the macros being edited by accident, not to hide anything: this tool is source-available, and the password is published here so that anyone can open the project and read the modules. VBA project protection is weak by design and is not a security measure.
| Sheet | Purpose |
|---|---|
INFO |
Bilingual (TR/EN) cover sheet describing the CC0 / public-domain terms under which community-submitted sentences are collected, plus the language, variant, and source metadata used for the MCV submission. |
ady-Cyrl-{empty} |
The blank template you copy for each new batch of sentences. Rename the copy to match the variant you're preparing (e.g. ady-Cyrl-x, kbd-Cyrl-x). |
LUT |
Lookup table of domain/topic codes (see Domain Codes Reference) used to fill in the Alanlar / Domains column. |
HowTo |
In-workbook, Turkish-language quick-reference for filling in the sentence sheet. |
| Column | Header | Notes |
|---|---|---|
| A | Variant | Optional. Write a code such as RU if the sentence includes Russian words or place/institution names, TR for Turkish words, and so on. Leave blank for sentences made up purely of Circassian vocabulary. |
| B | No | Auto-incrementing row number (formula — don't edit). |
| C | Kim / Who | Initials of the contributor who wrote the sentence, e.g. MUN. |
| D | Cümle / Sentence | The sentence text. Each cell should hold exactly one sentence and end with sentence-ending punctuation. |
| E | Uzunluk / Length | Character count, calculated automatically from column D (formula — don't edit). |
| F | Kelime / Words | Word count, calculated automatically from column D (formula — don't edit). |
| G | Alanlar / Domains | One to three domain codes from the LUT sheet, comma-separated (e.g. 5, 8). Defaults to 5 (General) until changed. |
| H, I | Onay-1 / Onay-2 (Verified-1/2) | Reserved for a two-stage review/proofreading sign-off. |
Copy the ady-Cyrl-{empty} sheet, rename it for your batch, and fill in the Variant, Kim/Who, Cümle/Sentence, and Alanlar/Domains columns as described above.
Click the Create TXT Files(s) button on the workbook to open the TXT File Creator & Validator form.
- Select Source Sheet — choose the sentence sheet you prepared.
- Limit — set the maximum number of sentences per output
.txtfile. - Select Target Folder — choose a destination folder (this also enables the Create TXT Files button).
- Click Create TXT Files to generate the grouped
.txtfiles. The generated file names appear in the list, and the form's second tab becomes available. - Optionally click Calculate Stats for a summary (total files, total sentences, total groups, min/max/average sentences per file and per group) or Open the destination folder to jump straight to Explorer.
- Choose a Mode (
validate,stats, ortrans) and a Lang. Code (adyorkbd). The action button relabels itself to match, e.g. "validate ady TXT files". - Optionally tick the checkbox to enable custom validation parameters (min/max sentence length, min/max word count); otherwise the built-in defaults are used.
- Click the action button. Each generated file is processed instantly, in-process — there's no external window to wait for. The console log and a final "Process completed for all files" message confirm when it's done.
.txt(UTF-8).tsv(UTF-8)
1. Grouped sentence files (primary output of tab 1):
{yyyy}-{mm}-{dd}-{file-number}-{ady|kbd}[-{variant}]-{domain-code(s), dash-separated}.txt
Examples: 2026-07-19-1-ady-5.txt (Adyghe, no variant, domain 5 = General) or 2026-07-19-1-ady-RU-5-8.txt (Adyghe, Russian-influenced variant, domains 5 and 8).
Each sentence ends up in exactly one file. The file it goes into is chosen by its full (language, variant, domain-code combination) — for a sentence tagged 5, 8, that's the single file whose name contains 5-8, never the 5 file and the 8 file. So the total number of sentences across every generated .txt file always equals the number of tagged rows in the source sheet — nothing is duplicated or dropped.
2. Additional files from the Validate/Transliterate engine (tab 2), named after the source file:
| Mode | Output |
|---|---|
validate |
{filename}_val.tsv, {filename}_inval.tsv |
stats |
{filename}_chars.tsv, {filename}_words.tsv |
trans |
{filename}_latn.txt |
This engine is a VBA port of circ.py; its rules and defaults are documented in the circassian-transliterate repository.
From the LUT sheet — used in the Alanlar / Domains column:
| Code | Domain | English (en) | Adyghe (ady) | Turkish (tr) | Russian (ru) |
|---|---|---|---|---|---|
| 1 | agriculture_food | Agriculture and Food | Мэкъу-мэщ ыкӏи гъомлапхъэ | Tarım ve Yemek | Сельское хозяйство и продовольствие |
| 2 | automotive_transport | Automotive and Transport | Ку сектор ыкӏи транспорт | Otomotiv ve Ulaşım | Автомобилестроение и транспорт |
| 3 | finance | Finance | Финанс | Finans | Финансы |
| 4 | service_retail | Service and Retail | Къулыкъу ыкӏи зырызыщэ | Hizmet ve Alışveriş | Сервис и розничная торговля |
| 5 | general | General | Пстэури | Genel | Общие сведения |
| 6 | healthcare | Healthcare | Псауныгъэ | Sağlık | Здравоохранение |
| 7 | history_law_government | History, Law and Government | Тарихъ, хабзэ ыкӏи къэралыгъо | Tarih, Hukuk ve Kamu Yönetimi | История, право и государственное управление |
| 8 | language_fundamentals | Language Fundamentals | Бзэм ылъапсэ (гущ. пае: пчъагъэхэр, хьарыфхэр, ахъщэ) | Dilin Temelleri | Основы языка |
| 9 | media_entertainment | Media and Entertainment | Медия ыкӏи зэщ тегъэуныгъ | Medya ve Eğlence | СМИ и развлечения |
| 10 | nature_environment | Nature and Environment | Чӏыопсыр ыкӏи тыкъэзыуцухьэрэ дунаир | Doğa ve Çevre | Природа и окружающая среда |
| 11 | news_current_affairs | News and Current Affairs | Къэбархэр ыкӏи хъурэ-шӏэрэхэр | Haberler ve Güncel Olaylar | Новости и текущие события |
| 12 | technology_robotics | Technology and Robotics | Технологие ыкӏи Роботик | Teknoloji ve Robotik | Технологии и робототехника |
Domain labels are given in all four languages exactly as they appear in the LUT sheet, so contributors can work in whichever language they read most comfortably.
- "Please select a destination folder" / "Please enter a valid line limit" — Both a target folder and a numeric line limit are required before Create TXT Files or Calculate Stats will run.
- Macros won't run — Make sure macros are enabled for the workbook (Trust Center, or Enable Content on the security bar), and that the file isn't blocked (right-click → Properties → Unblock).
- Nothing happens when saving
.txtfiles — Confirm you have write permission on the destination folder. - This tool is Windows + Excel desktop only; it will not run in Excel Online or Excel for Mac.
Special thanks to @bozden for the following work, which provided the infrastructure and the idea behind this application:
- circassian-transliterate (
circ.py) — developed by @bozden. - An Excel file customized for sentence preparation for MCV Adyghe and Kabardian ([ISO 639-2]:
ady,kbd). - The workbook's native VBA validation/transliteration engine (
mdlCircConst,mdlCircConstAdy,mdlCircConstKbd,mdlCircLib,mdlCircMain) originated as a direct port ofcirc.py's logic, used and redistributed with @bozden's explicit permission.
circassian-transliterate itself uses Turkish transliteration tables for Adyghe (ady→tr) and Kabardian (kbd→tr) developed by @nemerko, alongside additional sentence-analysis and statistical-reporting functions.
TXT File Creator & Validator for MCV was developed by nemerko to:
- Place sentences, tagged by topic, into
.txtfiles. - Make it easy to validate prepared sentences against MCV's requirements — using a VBA engine ported from
circassian-transliterate— so they can be loaded into the MCV system in bulk, without errors.
This software is released under the NEMERKO Limited Open License (NLO License), v2.0. It is source-available; it is not an open-source license as defined by the Open Source Initiative.
Purpose of these terms. The restrictions below exist to keep tools and data belonging to endangered language communities from being commodified or forked away from those communities, while still allowing individuals, communities and researchers to use, study and benefit from the software.
- Use permitted without a request. The source code may be viewed, run and used free of charge for personal, educational, academic-research and non-commercial language-documentation purposes. This expressly includes use by language-community volunteers who prepare, group or validate corpus data with the tool.
- Redistribution. Redistribution is permitted only in the original, unmodified form, with this license text and the author attribution intact.
- Modifications, forks and derivative works. Modifications, forks and derivative works require prior written permission from the author. Requests are assessed on the basis of the intended purpose. Permission may be granted free of charge or subject to a fee, may be granted with conditions, and may be refused. Citing the source does not substitute for permission.
- Commercial use. Commercial use — including integration into paid products, services or platforms — requires prior written permission from the author, under the same assessment as in clause 3.
- How to request permission. Permission requests should be submitted by opening an issue in this repository's issue tracker. A request should state who the applicant is, the intended purpose, the scope of the intended modification or use, and whether the use is commercial.
- Third-party components. Parts of this software are derived from
circassian-transliterate(circ.py) by @bozden and are used and redistributed with the explicit permission of its author. Any permission granted under clauses 3 and 4 covers only the present author's own contributions; rights in the derived components remain with their original author and must be obtained separately from him. - No warranty. The software is provided "as is", without any warranty or guarantee of performance.
Copyright © 2025–2026 M. Uğur Nemlioğlu
circassian-transliterate (circ.py): © 2025 @bozden
Note: GitHub's default Fork button is enabled for all public repositories and can't be disabled per-repo. It doesn't override the license terms above, but it's worth knowing the button will still be visible.
VBA application version (see note above — the Excel workbook itself is versioned separately, currently 2.3.0).
Versions follow Semantic Versioning: MAJOR.MINOR.PATCH — major for changes that break compatibility, minor for backward-compatible new features, patch for backward-compatible fixes.
| Version | Type | Date | Changes |
|---|---|---|---|
| v2.1.0 | minor | 2026-08-15 | Adds the three dialectal letters гь, кь and кӏь to the Adyghe and Kabardian mappers (gg, kk, kk'), and ships three corrections to the Adyghe mapper that were made after v2.0.0 was released. Affects output: (1) the dialectal letters were not defined, so the trailing ь was dropped and distinct words collapsed onto the same result — гьэ and гэ both produced ge; (2) the uppercase palochka Ӏ mapped to an empty string, so a word-initial Ӏоф came out as of instead of 'of; (3) the Latin form of кӏо ended with a Cyrillic о (U+043E) instead of the Latin o. A rule for ӏу that could never match was also removed; that one does not change output. |
| v2.0.0 | major | 2026-07-19 | Validation and transliteration logic ported directly into VBA (mdlCircConst, mdlCircConstAdy, mdlCircConstKbd, mdlCircLib, mdlCircMain), removing the external Python / circ.py / settings.ini dependency for the Validate/Transliterate tab. |
| v1.2.0 | minor | 2025-11-09 | Added feature to automatically group sentences according to variants. |
| v1.1.1 | patch | 2025-09-09 | Bug fix. |
| v1.1.0 | minor | 2025-08-15 | Added more error handling and user prompts. |
| v1.0.1 | patch | 2025-07-21 | circ.py integration paused, carried over to the next release. |
| v1.0.0 | major | 2025-04-30 | .xlsx file replaced with .xlsm; VBA form added. |