DEV Community: Từ Vựng 123

Aligning two subtitle files sentence by sentence for bilingual captions

Từ Vựng 123 — Thu, 01 Oct 2026 14:40:06 +0000

Bilingual subtitles, with the original line and its translation shown together, are one of the most effective tools for language learners watching films. The data problem behind them: the two subtitle files almost never share the same line breaks. One English line can map to two Vietnamese lines, or the other way round. Matching by line number breaks after the first mismatch.

Match by time overlap, not by index

Each subtitle cue has a start and an end time. For each line in the primary language, collect every secondary-language cue that overlaps it by a meaningful share of the secondary cue's own duration.

function parseSrt(text) {
  return text.trim().split(/\r?\n\r?\n/).map(block => {
    const lines = block.split(/\r?\n/);
    const [a, b] = lines[1].split(' --> ').map(t => {
      const [h, m, rest] = t.split(':');
      const [s, ms] = rest.split(',');
      return ((+h * 60 + +m) * 60 + +s) * 1000 + +ms;
    });
    return { start: a, end: b, text: lines.slice(2).join(' ') };
  });
}

const overlap = (x, y) => Math.max(0, Math.min(x.end, y.end) - Math.max(x.start, y.start));

function align(primary, secondary) {
  return primary.map(p => {
    const matches = secondary.filter(s => overlap(p, s) >= 0.3 * (s.end - s.start));
    return { ...p, translation: matches.map(s => s.text).join(' ') };
  });
}

With this English file

00:00:03,600 --> 00:00:06,000  Don't worry about me.

and a Vietnamese file split into two cues (Đừng lo and cho tôi.), align returns a single row: Don't worry about me. | Đừng lo cho tôi.

Why 30 percent

A small threshold glues in neighbouring cues that touch the edge of the line for a few milliseconds. A large threshold drops short translated cues that sit inside a long original line. Around a third of the secondary cue's duration is a reasonable starting point for film subtitles; check the result on a few minutes of each new film and adjust.

Things that still need a human

Translations that merge two original sentences into one long cue will appear next to both rows.
Subtitles with a constant offset (a different release of the film) must be shifted first. Find the offset from one clearly matching line and add it to every cue.

For an example of sentence-by-sentence bilingual subtitles in use, see Tu Vung 123, a language-learning site for Vietnamese speakers.

Converting numbered pinyin to tone marks in JavaScript

Từ Vựng 123 — Thu, 01 Oct 2026 14:40:05 +0000

Chinese learning material often stores pinyin with tone numbers (ni3 hao3) because it is easy to type and to store. Learners, however, need to see tone marks (nǐ hǎo). Converting between the two looks trivial until you meet ü, the neutral tone and the placement rules. Here is a small, dependency-free converter.

Where does the tone mark go?

The rule fits in three lines:

If the syllable has an a or an e, the mark goes on it.
If it has ou, the mark goes on the o.
Otherwise, the mark goes on the last vowel (so gui4 becomes guì and liu2 becomes liú).

Two more details: v or u: are common ASCII stand-ins for ü, and tone 5 (or 0) is the neutral tone, which has no mark.

Code

const MARKS = { a: 'āáǎà', e: 'ēéěè', i: 'īíǐì', o: 'ōóǒò', u: 'ūúǔù', ü: 'ǖǘǚǜ' };

function syllable(s) {
  const m = s.match(/^([a-zü:v]+)([0-5])$/i);
  if (!m) return s;
  let [, base, tone] = m;
  base = base.replace(/u:|v/g, 'ü');
  tone = Number(tone);
  if (tone === 0 || tone === 5) return base; // neutral tone
  const lower = base.toLowerCase();
  let idx;
  if (lower.includes('a')) idx = lower.indexOf('a');
  else if (lower.includes('e')) idx = lower.indexOf('e');
  else if (lower.includes('ou')) idx = lower.indexOf('o');
  else {
    // last vowel
    for (let i = lower.length - 1; i >= 0; i--) if ('iouü'.includes(lower[i])) { idx = i; break; }
  }
  if (idx === undefined) return base;
  const ch = lower[idx];
  return base.slice(0, idx) + MARKS[ch][tone - 1] + base.slice(idx + 1);
}

const toMarks = text => text.replace(/[a-zü:v]+[0-5]/gi, syllable);

toMarks('ni3 hao3');     // nǐ hǎo
toMarks('lv4 se4');      // lǜ sè
toMarks('xue2 sheng5');  // xué sheng
toMarks('gui4 liu2 dou1'); // guì liú dōu

What this does not handle

Tone sandhi. Pinyin is written with the original tones: two third tones in a row (nǐ hǎo) are written as 3-3 but spoken as 2-3. Showing the spoken tone is a separate, display-level decision.
Erhua (r suffix) works as long as the number comes after the whole syllable, e.g. huar1.
Capital letters keep working for the first letter, but the vowel lookup is lower-case only.

If you want to see pinyin with tone marks used for teaching, the Vietnamese course for learning Chinese (học tiếng Trung, Vietnamese for "learn Chinese") on Tu Vung 123 shows every word with characters, tone-marked pinyin and a Vietnamese meaning.

Building a Chinese stroke-order practice tool with hanzi-writer

Từ Vựng 123 — Thu, 01 Oct 2026 09:17:32 +0000

Chinese characters are written in a fixed stroke order, and learners who skip it end up with slow, messy handwriting and characters that handwriting keyboards fail to recognise. When we added a handwriting practice tool for Vietnamese learners of Chinese, we used hanzi-writer, an open-source JavaScript library that animates and quizzes stroke order. This post covers the parts that took more thought than expected.

What hanzi-writer gives you

hanzi-writer renders a character as SVG from stroke data (outline paths plus a median line for each stroke). It has three modes that map nicely onto how people learn:

Animate: draw each stroke in order so the learner sees the sequence.
Outline + trace: show a faint outline and let the learner draw over it.
Quiz: hide the character and check each stroke the learner draws against the expected median, with configurable leniency.

import HanziWriter from 'hanzi-writer';

const writer = HanziWriter.create('target', '好', {
  width: 240,
  height: 240,
  padding: 8,
  showOutline: true,
  charDataLoader: loadCharData, // see below
});

writer.quiz({
  leniency: 1.2,
  onMistake: s => console.log('wrong stroke', s.strokeNum),
  onComplete: s => console.log('mistakes:', s.totalMistakes),
});

Self-host the stroke data

By default the library fetches character data from a CDN, one JSON file per character. For a learning site that is a lot of third-party requests, and it breaks when the CDN is slow. We serve the data files from our own static path and pass a charDataLoader:

function loadCharData(char, onLoad, onError) {
  fetch(`/hanzi-data/${encodeURIComponent(char)}.json`)
    .then(r => (r.ok ? r.json() : Promise.reject(r.status)))
    .then(onLoad)
    .catch(onError);
}

Set long cache headers on that path; the stroke data for a character never changes.

Printable practice sheets

Learners still want paper. The classic practice grid is the 米字格 (a square with diagonal and centre guide lines). Because hanzi-writer outputs SVG, the same stroke data can be drawn into a printable grid: one row per character, the first cell solid, the next few cells as faint outlines to trace, the rest empty. Generating the sheet as SVG inside an HTML page and using @media print with @page { size: A4; margin: 12mm; } gives clean output without a PDF library.

Lessons

Quiz leniency matters. The default (1) can feel strict for complete beginners; raising it a little lowers frustration in the first weeks.
Show the stroke number on mistakes. "Wrong stroke" alone is not actionable.
Pair characters with their components (radicals). 好 is 女 + 子; learners remember two parts better than six loose strokes.

You can try the result, including the printable 米字格 sheets, on the Chinese handwriting practice page of Tu Vung 123 (the interface is in Vietnamese, but the writing area is self-explanatory).