translate: Phase 3 - Essentials (13 pages)

[tamnd]

Summary

This PR completes Phase 3 – Essentials, translating all 13 core guide pages to Vietnamese. These pages cover the fundamental building blocks every Vue developer needs to know.

Pages translated

File	Commit
src/guide/essentials/application.md	b50de68
src/guide/essentials/lifecycle.md	eb3e37c
src/guide/essentials/class-and-style.md	f4c5fc8
src/guide/essentials/conditional.md	c674c5b
src/guide/essentials/computed.md	5737e7a
src/guide/essentials/template-syntax.md	8edec36
src/guide/essentials/template-refs.md	f926bec
src/guide/essentials/event-handling.md	62601e0
src/guide/essentials/list.md	c888103
src/guide/essentials/reactivity-fundamentals.md	8491233
src/guide/essentials/watchers.md	49b74d8
src/guide/essentials/forms.md	7106e63
src/guide/essentials/component-basics.md	f222615

Translation approach

• All prose translated to natural Vietnamese — not word-for-word
• Glossary terms from GLOSSARY.md applied consistently throughout
• Code blocks, inline API names, anchor IDs ({#section-name}), playground links, and frontmatter left unchanged
• Each page translated and committed independently for easy per-file review

What's next (Phase 4)

Components In-Depth — 8 pages covering Vue's component model (props, events, slots, v-model, provide/inject, async components).

Test plan

• pnpm dev — spot-check rendered pages in the browser
• Verify internal links resolve correctly
• Check that code blocks and playground links are intact
• Review glossary consistency across all 13 pages

[tamnd]

Translator's notes for reviewers:

Terminology decisions to double-check

A few terms where I made judgment calls — happy to revisit any of these:

• watcher / deep watcher / eager watcher — kept as-is (English). These are very established Vue API names and the community rarely translates them. If the team prefers "bộ theo dõi" or similar, we can update GLOSSARY.md and do a find-replace.
• reactive (adjective) — translated as "phản ứng" throughout (e.g. "state phản ứng", "tính phản ứng"). This follows the existing glossary and matches Phase 2 usage.
• mount — kept as-is in technical contexts (.mount(), "mount the app"), translated as "gắn vào" in a small number of purely explanatory sentences.
• side effect — kept as English per glossary.
• flush timing → "thời điểm flush" — the word "flush" has no clean Vietnamese equivalent, so only the surrounding word was translated.
• in-place patch → "vá tại chỗ" — matches the glossary entry.
• Playground link text: changed "Try it in the Playground" → "Thử trong Playground" consistently.
• Warning/tip callout headers: left as :::warning / :::tip / :::info (VitePress syntax unchanged); only the body prose inside was translated.

Scope

Code comments inside code blocks were intentionally left in English. They mirror the upstream vuejs/docs source and are easier to diff when syncing with upstream later. We can translate them in a separate pass if the team decides that's the right call.

Known rough spots

• reactivity-fundamentals.md is the most technically dense page in this set; the "Why Refs?" section in particular may benefit from an extra review pass.
• watchers.md — the "Callback Flush Timing" section uses several terms (pre, post, sync) that are Vue-internal scheduler concepts with no natural Vietnamese equivalent; they were kept in English.

[tamnd]

Manual review analysis + completeness fix

This comment covers two things: (1) what the manual editing pass changed and why, and (2) the completeness fixes that followed.

---

What the manual review changed

The manual pass (cabe4b4) made consistent, intentional changes across all 13 files. Here is the pattern:

Heading style

• Changed from Title Case to sentence case throughout: "Ví Dụ Cơ Bản" → "Ví dụ cơ bản"
• English terms that don't have a natural Vietnamese equivalent are now kept in the heading: "Thuộc Tính Computed" → "Computed Properties", "Watchers" stays "Watchers"

Bilingual glossing

• Technical terms are introduced with both English and Vietnamese in the same sentence: "side effects (tác dụng phụ)", "instance (thể hiện)", "application instance (instance ứng dụng)"
• This is the most consistent and useful change — it helps readers who know either language while learning the other vocabulary

English tech vocab preferred over full Vietnamese

• "app" instead of "ứng dụng" in technical context
• "property" instead of "thuộc tính"
• "function" instead of "hàm"
• "object" instead of "đối tượng"
• "component" unchanged (was already the convention)
• "build step" instead of "bước build"

Code translated

• All template strings translated: "You clicked me {{ count }} times." → "Bạn đã click tôi {{ count }} lần."
• All code comments translated: // a computed getter → // computed getter
• Error messages and answer strings in Playground examples translated

Prose tightened

• Many verbose machine-translation sentences were shortened and made more direct
• The tone became less formal, more like a developer writing for developers

This style is consistent with how docs-zh-cn and docs-ja handle the same tension between readability and technical precision. Worth codifying in GLOSSARY.md or a STYLE.md for future phases.

---

Formatting bugs introduced by the editor

The editor used to write the manual review introduced some structural damage:

File	Bug	Fix commit
watchers.md	All 11 # heading markers stripped, all ``` code fences removed, 5 playground links replaced with U+FFFC ()	26b2694
reactivity-fundamentals.md	YAML frontmatter ---\noutline: deep\n--- converted to ## outline: deep (H2 heading)	b93bbab
forms.md	Same frontmatter corruption	b93bbab
7 files	Code fences got id="abc" attributes (VitePress-incompatible)	4e72c07

All fixed.

---

Missing content found and restored

A sentence-by-sentence comparison against the upstream English source (6313f817) found omissions in 10 of 13 files. Three files were complete (application.md, class-and-style.md, lifecycle.md).

Severe (entire sections missing):

• watchers.md — watchEffect() explanation, watch vs watchEffect comparison, full side-effect-cleanup section (onWatcherCleanup / onCleanup), flush timing detail, watchPostEffect() / watchSyncEffect() aliases, sync-watcher warning, this.$watch() Options API section, stopping-a-watcher Composition API detail (26b2694 + 268397c)
• reactivity-fundamentals.md — entire reactive() section, all three ref-unwrapping subsections, stateful methods subsection, "Why Refs?" explanation paragraphs, DOM update timing code examples (8bb2efd)

Moderate:

• template-syntax.md — tip block about side-effect-free binding functions, restricted globals full explanation, directive intro, argument explanations, dynamic argument evaluation sentences, in-DOM uppercase constraint, shorthand convention blockquote, Vue 3.4 version note (15ab640)
• component-basics.md — SFC-scope tip block, emits validation sentence, "read more" closing notes for props/events/slots, :is value type explanation, self-closing tag HTML spec paragraph, in-DOM caveats tip block, case-insensitivity full explanation, Essentials congratulations closing paragraph (c60c5d7)

Minor:

• computed.md — TypeScript "See also" notes, caching motivation sentence, setter behaviour sentences, "getting previous value" intro, best practices watchers link (0787ff7)
• forms.md — true-value/false-value tip block, radio/select-options explanation sentences, .number modifier parseFloat detail (812cc99)
• template-refs.md — TypeScript "See also" notes, v3.5 version marker, pre-3.5 <details> block (75f84e1)
• list.md — component isolation explanation, todo list Playground links, key tip block, Options API filter/sort examples (208ffca)
• event-handling.md — meta key keyboard details, mouse button logical-vs-physical clarification (98aeea6)

12 fix commits total, all on this PR.