Roadmap (estimation)

[tamnd]

1. Corpus Overview

Total corpus extracted from CPython 3.14 documentation via make gettext.

Section	Files	.po Lines	Messages	Words	Avg words/msg
library/	326	230,520	38,108	791,751	20.8
whatsnew/	25	148,354	25,729	566,964	22.0
c-api/	77	37,192	6,322	120,511	19.1
howto/	29	28,739	3,552	102,918	29.0
reference/	11	18,462	3,183	67,740	21.3
using/	9	8,544	1,587	30,792	19.4
faq/	9	7,578	1,083	27,262	25.2
extending/	7	5,694	627	21,920	35.0
Root pages	9	5,666	432	20,017	46.3
deprecations/	14	3,302	542	7,116	13.1
installing/	1	339	53	1,003	18.9
distributing/	1	33	2	30	15.0
tutorial/	17	11,697	1,309	~15,000	11.5
Total	535	506,120	82,930	~1,772,024

2. Translation Status

Completed (unfuzzied, human-reviewed)

File / Group	Messages	Est. Words	Status
bugs.po	~30	~500	Done
tutorial/appetite.po (ch1)	24	~300	Done
tutorial/interpreter.po (ch2)	34	~430	Done
tutorial/introduction.po (ch3)	120	~1,680	Done
tutorial/controlflow.po (ch4)	209	~2,920	Done
library/functions.po	~350	~8,500	Done
GLOSSARY.md	--	--	Done
Subtotal done	~767	~14,330

Remaining

Section	Messages	Words	% of total words
library/ (excl. functions.po)	~37,758	~783,251	44.2%
whatsnew/	25,729	566,964	32.0%
c-api/	6,322	120,511	6.8%
howto/	3,552	102,918	5.8%
reference/	3,183	67,740	3.8%
using/	1,587	30,792	1.7%
faq/	1,083	27,262	1.5%
extending/	627	21,920	1.2%
Root pages (excl. bugs.po)	~402	~19,517	1.1%
tutorial/ (ch5-17, 13 files)	~542	~9,070	0.5%
deprecations/	542	7,116	0.4%
installing/	53	1,003	0.1%
distributing/	2	30	0.0%
Total remaining	~81,383	~1,758,094

Overall completion: ~0.9% by messages, ~0.8% by words.

3. Velocity Model

Baseline derived from observed output: 1 tutorial file per day. Tutorial averages 882 words/file across 17 files, giving a baseline of ~900 words/day.

Content type	Words/day	Ratio to baseline	Reason
Tutorial-density (baseline)	900	1.0x	Clear prose, familiar Python concepts
Dense technical (reference, C-API)	600	0.7x	Heavy terminology, long paragraphs
How-to / FAQ	1,000	1.1x	Self-contained, narrower domain
Library reference (Tier A)	1,000	1.1x	Known APIs, GLOSSARY settled by then
Library reference (Tier B/C)	1,100	1.2x	Repetitive patterns, faster once in flow

For multi-contributor estimates, velocity scales linearly per independent file (contributors do not share files).

Scenario	Effective words/day
1 contributor	900
2 contributors	1,800
3 contributors	2,700

4. Phases

Phase 0 (in progress): PEP 545 Language-Switcher Seed

Goal: get docs.python.org/vi/ into the language switcher. PEP 545 requires bugs.po, tutorial/*.po, and library/functions.po fully translated.

File	Messages	Est. Words	Status
bugs.po	~30	~500	Done
tutorial/appetite.po (ch1)	24	~300	Done
tutorial/interpreter.po (ch2)	34	~430	Done
tutorial/introduction.po (ch3)	120	~1,680	Done
tutorial/controlflow.po (ch4)	209	~2,920	Done
tutorial/datastructures.po (ch5)	142	~1,990	Remaining
tutorial/modules.po (ch6)	128	~1,790	Remaining
tutorial/inputoutput.po (ch7)	116	~1,620	Remaining
tutorial/errors.po (ch8)	138	~1,930	Remaining
tutorial/classes.po (ch9)	168	~2,350	Remaining
tutorial/stdlib.po (ch10)	72	~1,010	Remaining
tutorial/stdlib2.po (ch11)	84	~1,320	Remaining
tutorial/venv.po (ch12)	44	~680	Remaining
tutorial/whatnow.po (ch13)	18	~280	Remaining
tutorial/floatingpoint.po (app A)	72	~1,190	Remaining
tutorial/interactive.po (app B)	12	~150	Remaining
tutorial/appendix.po (app C)	32	~450	Remaining
tutorial/index.po	8	~110	Remaining
library/functions.po	~350	~8,500	Done
Phase 0 total	~1,609	~24,200	In progress

Remaining in Phase 0: 13 tutorial files + index (~542 msgs, ~9,070 words).

Estimate at 900 words/day: ~10 more days to finish Phase 0.

Phase 1: Root Pages and Glossary (~20k words, 23 files)

Short, high-visibility files. Every reader sees these in the site margins. glossary.po is the exception -- large and terminology-defining, do it last.

File	Messages	Est. Words	Notes
sphinx.po	~20	~200	Sphinx UI strings
improve-page.po	~30	~300	"Help improve this page" banner
improve-page-nojs.po	~25	~250	Same, no-JS variant
copyright.po	~10	~100	Copyright footer
contents.po	~15	~150	Table of contents page
about.po	~20	~400	About page
license.po	~40	~800	License page
deprecations/ (14 files)	542	7,116	Pending removal notices
glossary.po	~232	~11,000	Terminology definitions
Phase 1 total	~934	~20,316

glossary.po is the gate: every new term it introduces must go into GLOSSARY.md before the string is committed. Finish everything else first.

Estimate at 900 words/day: ~23 days solo. At 2 contributors: ~11 days.

Phase 2: Language Reference (~66k words, 11 files)

The formal specification of Python semantics. Slower pace (dense), but high value for serious readers.

File	Est. Words	Notes
reference/introduction.po	~1,000	Short
reference/lexical_analysis.po	~6,500	Tokens, literals
reference/datamodel.po	~18,000	Largest; objects, types, protocols
reference/executionmodel.po	~3,500	Scopes, namespaces
reference/import.po	~9,000	Import system
reference/expressions.po	~10,500	Operator precedence, evaluation
reference/simple_stmts.po	~7,500	Assignment, del, return, ...
reference/compound_stmts.po	~8,500	if, for, with, def, class, ...
reference/toplevel_components.po	~1,200	Interactive, file input
reference/grammar.po	~600	BNF grammar listing
reference/index.po	~100	Index page
Phase 2 total	~66,400	11 files

Suggested order: introduction -> executionmodel -> lexical_analysis -> simple_stmts -> compound_stmts -> expressions -> import -> datamodel -> grammar -> index. Tackle datamodel last among the large files; it references the most terminology.

Estimate at 600 words/day (dense): ~111 days solo. At 2 contributors: ~55 days.

Phase 3: How-Tos and FAQ (~131k words, 38 files)

Self-contained documents, narrower terminology than the library. Good volunteer targets -- each file is independently ownable.

3a. How-To Guides (29 files, ~103k words)

File	Est. Words	Priority
howto/logging.po	~18,000	High
howto/logging-cookbook.po	~14,000	High
howto/argparse.po	~10,000	High
howto/urllib2.po	~8,000	High
howto/regex.po	~7,500	High
howto/unicode.po	~6,500	High
howto/functional.po	~6,000	Medium
howto/descriptor.po	~5,500	Medium
howto/enum.po	~5,000	Medium
howto/sorting.po	~3,500	Medium
howto/asyncio-conceptual.po	~3,000	Medium
howto/annotations.po	~2,500	Medium
howto/clinic.po	~4,000	Low
howto/ipaddress.po	~2,500	Low
howto/instrumentation.po	~2,000	Low
Remaining 14 howto files	~5,000	Low
Howto subtotal	~103,000

3b. FAQ (9 files, ~27k words)

File	Est. Words	Priority
faq/programming.po	~12,000	High
faq/general.po	~5,500	High
faq/library.po	~4,000	Medium
faq/design.po	~3,000	Medium
faq/windows.po	~1,500	Medium
faq/extending.po	~800	Low
faq/gui.po	~600	Low
faq/installed.po	~400	Low
faq/index.po	~100	Low
FAQ subtotal	~27,900

Phase 3 total: ~130,900 words, 38 files.

Estimate at 1,000 words/day: ~131 days solo. At 3 contributors owning separate files: ~44 days.

Phase 4: Installing, Using, Extending (~54k words, 18 files)

Practical setup sections. using/ gets real traffic from new Python users.

4a. Installing and Distributing (2 files, ~1k words)

File	Messages	Est. Words
installing/index.po	53	~1,003
distributing/index.po	2	~30
Subtotal	55	~1,033

Both finishable in one sitting. Do these first inside Phase 4.

4b. Using Python (9 files, ~31k words)

File	Est. Words	Notes
using/windows.po	~9,000	High traffic
using/cmdline.po	~7,500	High traffic
using/configure.po	~6,000	Build config
using/unix.po	~3,500	Unix install
using/mac.po	~2,500	macOS notes
using/android.po	~1,200	New (3.13+)
using/ios.po	~1,000	New (3.13+)
using/editors.po	~200	IDE list
using/index.po	~100	Index
Subtotal	~31,000

4c. Extending Python (7 files, ~22k words)

File	Est. Words	Notes
extending/extending.po	~8,000	C extension basics
extending/newtypes.po	~5,500	New types
extending/newtypes_tutorial.po	~3,500	Tutorial
extending/embedding.po	~2,500	Embed Python in C
extending/building.po	~1,500	Build setup
extending/windows.po	~800	Windows notes
extending/index.po	~100	Index
Subtotal	~21,900

Phase 4 total: ~53,933 words, 18 files.

Estimate at 900 words/day: ~60 days solo. At 2 contributors: ~30 days.

Phase 5: C API Reference (~121k words, 77 files)

Target audience: C extension and embedding authors. Terminology-heavy. Begin only after GLOSSARY.md is stable, because mistakes here are painful to sweep later.

Large files (>3,000 words each)

File	Est. Words
c-api/typeobj.po	~15,000
c-api/arg.po	~9,000
c-api/unicode.po	~8,500
c-api/structures.po	~6,000
c-api/object.po	~5,500
c-api/exceptions.po	~5,000
c-api/memory.po	~4,500
c-api/init_config.po	~4,000
c-api/long.po	~4,000
c-api/dict.po	~3,500
c-api/list.po	~3,000
c-api/bytes.po	~3,000
Large subtotal	~71,000

Medium files (1,000-3,000 words, ~30 files)

abstract, allocation, bool, buffer, call, capsule, code, codec, complex, datetime, float, function, import, iter, marshal, module, sequence, set, slice, sys, threads, tuple, type, weakref, and others. ~40,000 words combined.

Small files (<1,000 words, ~35 files)

Index files, cross-reference stubs, narrow APIs. ~9,500 words combined.

Phase 5 total: ~120,511 words, 77 files.

Estimate at 600 words/day (dense): ~201 days solo. At 3 contributors: ~67 days.

Phase 6: Library Reference (~792k words, 325+ files)

The mountain. Work by reader traffic, not alphabetically. Three tiers.

Tier A -- Top 20 Modules by Reader Traffic

Module	File(s)	Est. Words
os	library/os.po	~28,000
typing	library/typing.po	~18,000
asyncio	library/asyncio*.po (12 files)	~35,000
datetime	library/datetime.po	~10,000
argparse	library/argparse.po	~10,000
sqlite3	library/sqlite3.po	~10,000
re	library/re.po	~9,000
subprocess	library/subprocess.po	~9,000
sys	library/sys.po	~9,000
io	library/io.po	~8,500
pathlib	library/pathlib.po	~8,000
logging	library/logging.po	~8,000
itertools	library/itertools.po	~7,000
collections	library/collections.po	~7,000
urllib	library/urllib*.po (4 files)	~7,000
http	library/http*.po (4 files)	~9,000
functools	library/functools.po	~5,000
pickle	library/pickle.po	~5,500
json	library/json.po	~3,500
math	library/math.po	~4,500
Tier A subtotal	~43 files	~210,000

Tier A estimate at 1,000 words/day: ~210 days solo. At 3 contributors: ~70 days.

Tier B -- Active Stdlib (~250 files, ~480k words)

Modules still widely used in Python 3.x but lower traffic than Tier A.

abc, builtins, concurrent, contextlib, copy, csv, dataclasses, dis, email, enum, fnmatch, fractions, gc, glob, hashlib, heapq, html, inspect, ipaddress, keyword, linecache, multiprocessing, operator, platform, pprint, queue, random, shutil, signal, socket, socketserver, ssl, string, struct, tarfile, tempfile, textwrap, threading, time, token, traceback, types, unittest, uuid, warnings, weakref, xml, zipfile, zipimport, and others.

Tier B estimate at 1,100 words/day: ~436 days solo. At 3 contributors: ~145 days.

Tier C -- Niche, Legacy, or Removed Modules (~80k words)

Low reader volume. Sphinx falls back to English if strings stay fuzzy. Do last or deliberately skip.

cgi, cgitb, chunk, crypt, imaplib, mailbox, msilib, nis, nntplib, optparse, ossaudiodev, pipes, sndhdr, sunau, telnetlib, turtledemo, wave, xdrlib, parts of xml.etree.

Tier C estimate at 1,100 words/day: ~73 days solo. At 2 contributors: ~36 days.

Phase 7: What's New (policy, not scope)

567,000 words across 25 files. No PEP 545 translation team has ever translated the full whatsnew/. The changelog alone is ~500,000 words.

Policy:

• Translate only whatsnew/3.14.po (current release) and whatsnew/index.po.
• All older whatsnew/ files remain excluded via Makefile's EXCLUDED pattern; Sphinx falls back to English source.
• When CPython branches 3.15, add whatsnew/3.15.po; keep the current two releases in scope.
• Do not backfill historical releases.

File	Est. Words	Action
whatsnew/3.14.po	~10,000	Translate
whatsnew/index.po	~200	Translate
whatsnew/changelog.po	~500,000	Exclude permanently
whatsnew/2.0.po through whatsnew/3.13.po	~57,000	Exclude permanently

Estimate per release cycle at 1,000 words/day: ~10 days. Target: each new whatsnew/ done within 2 weeks of CPython branching.

Phase 8: Carry-Forward Maintenance (continuous)

CPython docs change every release cycle.

Checklist per CPython release:

1. Bump CPYTHON_CURRENT_COMMIT in Makefile to the new release tag.
2. Re-run make gettext against the pinned CPython checkout.
3. Run sphinx-intl update -l vi against the new .pot files.
4. msgmerge marks changed strings fuzzy. Resolve each one.
5. Add new terms to GLOSSARY.md.
6. Add new whatsnew/ file for the new release; exclude the oldest one.
7. Push to Transifex; python-docs-vi mirror auto-syncs hourly.

Estimate: 5-15 days per CPython minor release, depending on upstream churn.

5. Duration Summary

All estimates assume observed baseline of 900 words/day (1 tutorial file/day). Content-type adjustments applied per phase.

Phase	Section	Words	Solo days	2 contrib.	3 contrib.
0	PEP 545 seed	~24,000	Done	Done	Done
1	Root pages + glossary	~20,316	~23 days	~11 days	~8 days
2	Language reference	~66,400	~111 days	~55 days	~37 days
3	How-to + FAQ	~130,900	~131 days	~65 days	~44 days
4	Using + extending + installing	~53,933	~60 days	~30 days	~20 days
5	C API	~120,511	~201 days	~100 days	~67 days
6a	Library Tier A	~210,000	~210 days	~105 days	~70 days
6b	Library Tier B	~480,000	~436 days	~218 days	~145 days
6c	Library Tier C	~80,000	~73 days	~36 days	~24 days
7	Whatsnew (per release)	~10,000	~10 days	~5 days	~4 days
8	Maintenance	--	5-15 days/release	--	--

"Usable core" checkpoint (Phases 1-5 complete): tutorial + reference + howto + faq + using + extending + C-API all in Vietnamese.

• Solo: ~526 days (~1.5 years)
• 2 contributors: ~261 days (~9 months)
• 3 contributors: ~176 days (~6 months)

"Full stdlib Tier A" checkpoint (Phase 6a done, cumulative from Phase 1):

• Solo: ~736 days (~2 years)
• 3 contributors: ~246 days (~8 months)

"Substantially complete" checkpoint (Phase 6b done, cumulative from Phase 1):

• Solo: ~1,172 days (~3.2 years)
• 3 contributors: ~391 days (~13 months)

6. Milestones Tracker

Milestone	Status	Notes
PR #1: MT seed of PEP 545 files	Done	bugs.po, tutorial/*.po, functions.po
GLOSSARY.md landed	Done
Pronoun and heading-style policies written	Done	In GLOSSARY.md
bugs.po fully unfuzzied	Done
tutorial/ ch1-4 unfuzzied (appetite, interpreter, introduction, controlflow)	Done
tutorial/ ch5-17 unfuzzied (13 files remaining)	In progress	~9,070 words left
library/functions.po fully unfuzzied	Done
Language-switcher PR to python/docsbuild-scripts	Blocked	Needs all tutorial/*.po done first
Phase 1 complete (root pages + glossary)
Phase 2 complete (language reference)
Phase 3 complete (howto + faq)
Phase 4 complete (using + extending)
Phase 5 complete (C API)
PSF CLA signed by coordinator		Required for org transfer
Transfer request to python/ GitHub org		After PEP 545 criteria met
Phase 6a complete (library Tier A)
Phase 6b complete (library Tier B)

7. Contributor Workflow

Claiming a file

1. Open an issue: Translate library/os.po -- assign to self.
2. Branch name: replace / with -, e.g. library-os, reference-datamodel.
3. Open a draft PR immediately. Prevents duplicate work.
4. Only unfuzzy strings you have read and are confident are correct.
5. Label the issue and PR with the phase.

Style rules (non-negotiable)

• Pronoun: bạn throughout (decided in GLOSSARY.md).
• Headings: sentence case, imperative form where the English is imperative.
• Code literals: never translate; wrap in backticks exactly as upstream.
• Cross-references (:func:, :class:, :mod:): keep the markup; only translate the surrounding prose, not the target name.
• Terminology: defer to GLOSSARY.md. If a term is missing, add it first, then use it.

Review criteria before merging

• No fuzzy flags remain in the file.
• Rendered output checked via make -C cpython html SPHINXOPTS="-D language=vi".
• At least one reviewer who did not write the strings has approved.
• GLOSSARY.md updated for any new terms introduced.

8. Scope Exclusions

• CPython source comments and docstrings -- work from .pot output only; the Sphinx build is the boundary.
• Translation memory server -- sphinx-intl + msgmerge is sufficient until the project has at least 10 active contributors.
• Automated review -- every fuzzy removal is a human decision.
• Historical whatsnew/ files (pre-3.13) -- excluded permanently via Makefile.
• Library Tier C -- deferred indefinitely; English fallback is acceptable for low-traffic legacy modules.

[tamnd]

Note

The roadmap above is a rounded estimation. It will be updated based on actual progress. A more accurate version will be maintained in the main python-docs-vi repo.