foxnail

JSDoc 4개국어 지원 · OPEN GRID 1.4.0

2026. 07. 17  ·  OPEN GRID

OPEN GRID 1.4.0 의 변경은 두 가지입니다. 공개 API 문서의 JSDoc 891블록을
한국어 · English · 日本語 · 中文 4개국어로 다시 썼고, 코어 안에 있던 확장 레지스트리
TypedRegistry 를 공개 API 로 노출했습니다.

변동사항

🧩 확장 레지스트리 공개 (TypedRegistry)

셀 렌더러·포맷터 같은 커스텀 레지스트리를 직접 만들 때 쓰는 등록 정책 엔진입니다.
구현은 코어 안에 이미 있었고, 이번에 공개 API 로 노출했습니다.

  • 등록마다 결과를 반환합니다 — added(신규) · replaced(덮어씀) · kept(기존 유지) · rejected(거부).
    유지·거부에는 이유(reason)가 따라옵니다. Map 만으로는 얻을 수 없는 정보입니다.
  • og: · og- 로 시작하는 이름은 그리드 예약 접두사이므로 등록이 거부됩니다
    (RESERVED_PREFIXES · isReserved).
  • duplicatePolicy: 'protect-builtin' 으로 내장 항목의 덮어쓰기를 차단할 수 있습니다.
  • 관련 타입 10종을 함께 공개했습니다.

순수 추가이므로 기존 사용자의 대응 작업은 없습니다. OpenGrid.registerRenderer 의 내부 동작은
그대로이고 정책 엔진을 거치지 않습니다. 번들 영향은 gzip 기준 80바이트로,
진입점이 4,441B 에서 4,521B 가 되었습니다. 예산은 8,000B 이고 ES 코어 청크는 변동 없습니다.

공개 API 문서를 4개국어로

대상은 TypeDoc 가 렌더하는 공개 선언 전 파일, JSDoc 891블록입니다.
이를 한국어 · English · 日本語 · 中文 으로 작성했습니다.
분량보다 먼저 정해야 할 것은 번역 경로였습니다.

번역 원본 선정 기준

어떤 언어를 원본으로 삼아 옮길지는 언어쌍의 구조적 거리로 갈랐습니다.

  • 일본어는 한국어 기준입니다. 한국어와 일본어는 어순(주어-목적어-서술어)·조사·수식 구조가
    거의 1:1로 대응해 문장 재조립이 필요 없습니다.
  • 중국어는 영어 기준입니다. 영어와 중국어는 모두 주어-서술어-목적어 어순에 굴절이 없어
    문장 구조를 그대로 옮길 수 있습니다.
  • 단 뜻의 정본은 한국어입니다. 영어를 경유하면 영어 문서의 오차까지 함께 전파되기 때문입니다.

정본 대조로 발견한 영문 문서 오차 2건

한국어를 정본으로 두고 대조한 결과, 영어 문서 두 곳이 한국어와 어긋나 있었습니다.

  • 차트 계열 구분 무늬 설명에서 한국어·일본어·중국어는 “색과 함께 또는 색 대신” 두 경우를 모두 기술하는데,
    영어는 “색뿐 아니라 모양으로도”로 적혀 “색 대신” 쪽이 빠져 있었습니다.
    색 구분이 어려운 사용자에게는 이 선택지가 핵심 기능이므로 영문만 정보가 결손된 상태였습니다. 수정했습니다.
  • 나머지 하나는 한국어에 없는 문장이 영어에만 추가돼 있던 경우로, 한국어에 맞춰 정리했습니다.

병기 형식 변경 — 슬래시에서 문단 분리로

종전 형식은 설명. / English. 처럼 슬래시 하나로 두 언어를 한 줄에 붙이는 방식이었습니다.
이 형식은 문서로 렌더링될 때 한국어와 영어가 한 문단에 통째로 이어져 나옵니다.
소스에서 줄을 바꿔도 마크다운이 단일 줄바꿈을 무시하기 때문입니다.
빈 줄로 문단을 나누는 방식으로 바꿨습니다. 언어마다 문단이 분리돼 렌더링됩니다.

예시 코드 줄 끝 주석은 영어 하나로 통일했습니다. 한 줄짜리라 문단 분리가 불가능하고,
여러 언어를 넣으면 다시 슬래시 병기로 회귀합니다. 코드 자체가 영어로 작성되는 점도 감안했습니다.

README 일본어·중국어판 추가와 원본 갱신

README.ja.md · README.zh.md 를 추가했고 npm 페이지에 그대로 노출됩니다.
번역 과정에서 원본이 갱신되지 않았다는 사실이 드러났습니다. 기능표가 초기 버전 시점에 멈춰 있어
이후 추가된 범위 선택·마스터/디테일·수식 셀·통합 차트·조건부서식·실시간 데이터가 누락돼 있었고,
테마 수도 12개로 적혀 있었으나 실제는 15개입니다. 원본을 먼저 갱신한 뒤 옮겼습니다.
순서를 반대로 했다면 낡은 내용이 세 언어로 복제됩니다.

트레이드오프와 제외 범위

  • 문서 길이가 늘었습니다. 4개국어를 한 블록에 담았으므로 편집기에서 함수 설명을 띄우면
    그만큼 긴 호버 툴팁이 뜹니다. 4개국어 지원과 맞바꾼 비용입니다.
  • 번역 제외 6블록. 문서에 노출되지 않는 내부 표시가 붙은 5개 블록과,
    설명할 산문이 없는 코드 조각 1개입니다. 원문에 없는 설명을 새로 만들지 않는다는 원칙에 따라 그대로 두었습니다.

금번에는 JSDoc과 각종 주석을 변경하였습니다

주석을 걷어낸 코드가 이전과 동일한지 전수 대조했고, 테스트 1,711건이 모두 통과합니다.
주석은 배포본에서 제거되므로 문서 작업으로 늘어난 번들 용량은 0바이트입니다.
앞서 적은 80바이트는 TypedRegistry 공개분입니다.
TypedRegistry 공개는 순수 추가이므로 기존 API·동작·화면은 이전과 동일합니다.

설치

npm install open-grid

API 문서(4개국어)
· 데모
· npmjs.com/package/open-grid

OPEN GRID 는 순수 JavaScript 데이터 그리드입니다. React·Vue·Angular·jQuery·Vanilla 어디서든 동작합니다. · MIT License

공유하기