AGENT SKILL

i18n-layout

Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.

License 许可
AGPL-3.0
最近更新
2026-11-14
Stars
★ 25
Forks
9

01 前言 Front Matter

name
i18n-layout
owner
i18n-specialist
scope
co-work
status
active
version
1.1.2
metadata
{ "type": "process", "triggers": [ "character encoding", "RTL", "bidi", "font selection", "CRLF", "BOM" ] }
description
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
last_reviewed
1794528000000
prerequisites
none

03 SKILL.md 正文

Purpose

Defines how text is encoded, ordered, and rendered across scripts. Locale configuration (the i18n-locale-config skill) decides what a locale is; formatting (the i18n-formatting skill) decides how values are written; this skill decides how text physically lays out: bytes, direction, and glyphs.

Character Encoding

UTF-8 is the only default. Every file this workspace produces — source, docs, JSON, CSV — is UTF-8 unless a declared external interface demands otherwise.

Legacy Korean code pages (CP949 / EUC-KR)

  • Windows Korean legacy content is often CP949 (a superset of EUC-KR). Opening it as UTF-8 produces mojibake; opening UTF-8 as CP949 silently double-encodes.
  • When consuming legacy Korean files, detect the code page first, convert once to UTF-8, and never round-trip back. Conversion tools may fail on characters that exist in CP949 but not EUC-KR — convert with the CP949 mapping.
  • Windows terminals default to a legacy code page; garbled Korean in console output is a terminal-encoding symptom, not a data corruption. Fix the terminal (UTF-8 code page) before touching the data.

BOM pitfalls

  • A UTF-8 BOM is an invisible byte sequence (EF BB BF) at the file head. It breaks shebang lines, JSON parsers that expect { as the first byte, and any content-hash or byte-diff check.
  • Tools can materialize a BOM unintentionally: writing the six ASCII characters that spell a BOM escape as literal text causes some editors and file APIs to decode it into a real BOM byte. After any edit involving BOM-related escapes, verify the file head with byte-level inspection, not a text viewer.
  • If a BOM must be removed, rewrite the file's first bytes programmatically — text-editor deletion can leave the invisible residue behind.

Line endings

  • Repositories store LF; Windows checkouts may see CRLF. Both are fine — mixed endings within one file are not: they break byte-level verification and make diffs noisy.
  • Keep each file uniform. When a byte-exact check exists for a file, match the ending that check expects.

RTL and BiDi

Arabic (ar) is right-to-left — constitution §4.1 requires dir="rtl" on the root element (or direction: rtl in CSS) when ar is the active locale.

Logical vs visual ordering

  • Store and exchange text in logical order — the order a reader types and reads it. Never store visually-reordered text; reversal is the renderer's job (the Unicode bidi algorithm), not the data model's.
  • Manually reversing an RTL string breaks searching, cursor movement, and every downstream consumer. If a pipeline outputs reversed Arabic, the bug is in that pipeline.

Embedding LTR runs inside RTL text

Numbers, code identifiers, and URLs inside Arabic sentences are LTR islands:

  • In HTML, wrap them with <bdi> or apply unicode-bidi: isolate so the bidi algorithm contains them.
  • In plain text, use the directional marks (RLM/LRM) at run boundaries — sparingly; stray marks are invisible characters that pollute diffs and search.
  • Directional icons and progress affordances mirror in RTL layouts; logos, media playback controls, and clocks do not.

Script-Specific Fonts

Hangul (Korean)

Hangul fonts are heavy: the script has 11,172 precomposed syllable blocks, so full fonts reach multiple megabytes. This drives every practical rule:

Context Guidance
Decks / UI (per co-deck practice) Sans-serif faces Pretendard and NanumSquareNeo are the house choices for Korean presentation material
Web Serve Noto Sans KR / Noto Serif KR with unicode-range subsetting (split woff2 chunks); never ship one monolithic Korean font
System fallbacks Windows ships a default Korean sans (Malgun Gothic); macOS ships its own — declare both after the web font in the stack, then a generic sans-serif
Monospace / tables Hangul is double-width in monospace contexts — never column-align Korean text with ASCII space counts; the widths will not match rendering

The font pipeline (download, subsetting, theme token wiring) lives in the co-deck variant's design and theme-authoring skills — this suite holds the selection knowledge, co-deck holds the tooling. Do not duplicate font tooling here.

Shared-ideograph scripts (zh / ja)

Chinese, Japanese, and Korean share Han ideographs but render them with regional glyph standards. A font localized for one region shows the wrong regional style for another (stroke shapes differ visibly). Match the font's locale to the content locale (zh-CN content gets a CN-standard font), and never assume one CJK font covers all three locales acceptably for native readers.

Mixed-script line height

Latin and Hangul/Han glyphs have different natural heights; mixed-script lines need explicit line-height (about 1.5 for Korean body text) rather than the tighter Latin default, or the Korean reads cramped.

HWP Documents

HWP/HWPX authoring and conversion tooling is provided by the co-work hwp-document-processing skill — the full pipeline (read, generate, fill, patch, lint, compare + old-vs-new amendment comparison table, render/export, HWPX→HWP5 reverse conversion) runs through the scripts/hwp/ adapter. This suite keeps only the layout concerns: HWP content brought into this workspace still converts to UTF-8 at the boundary, regardless of which tool converts (see Legacy Korean code pages above).

Boundary

  • Locale IDs, collation, timezones: i18n-locale-config.
  • Per-locale value formatting (dates, numbers, currency): i18n-formatting.
  • Translating a specific file (hash sync, diff preview): the translate skill.

Context

See docs/co-work.context.md for project context and the document-production lifecycle.

When to Use

  • When a co-work task touches legal or legacy Korean character encodings, RTL/BiDi rendering, or script-specific font selection.

Execution Steps

  1. Receive dispatch from PM with task parameters and document anchors.
  2. Execute the skill procedure against the artifacts named in the task scope.
  3. Report results to the dispatching agent with evidence links.

Output Format

Structured markdown report delivered to the dispatching agent, citing document anchors where applicable.

Related Skills

  • Owner agent: i18n-specialist
  • Common skill: i18n-layout (templates/common/skills/i18n-layout/SKILL.md, v1.1.1) - this co-work copy overrides only line 92.

04 同仓库更多 Skills

5throck
5throck/ai-workspace-standards

i18n-layout

Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.

★ 25
5throck
5throck/ai-workspace-standards

i18n-layout

Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.

★ 25
5throck
5throck/ai-workspace-standards

i18n-layout

Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.

★ 25
5throck
5throck/ai-workspace-standards

i18n-layout

Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.

★ 25
5throck
5throck/ai-workspace-standards

i18n-layout

Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.

★ 25
5throck
5throck/ai-workspace-standards

discovery

暂无简介

★ 25