이 문서는 다음 유지보수자를 위한 인수인계 기록이다.

이번 패스의 핵심은 문자열, 메뉴, 언어 URL 정책을 모두 중앙화해서, 나중에 언어가 더 늘어나도 같은 규칙으로 확장할 수 있게 만든 것이다.

이번 패스의 핵심 수정

1) 메뉴의 단일 원본을 config/_default/hugo.toml 로 이동

파일:

  • config/_default/hugo.toml

변경 내용:

  • [[menus.main]] 을 한 곳에만 두어 전체 언어가 같은 메뉴 정의를 공유하도록 정리했다.
  • identifier 는 번역 키와 동일하게 유지했다.
  • pageRef 기반으로 현재 언어의 대응 페이지를 자동 연결하도록 정리했다.

중요한 이유:

  • 메뉴 문구를 언어 파일마다 복제하지 않아도 된다.
  • 새 언어를 추가해도 메뉴 구조는 한 번만 수정하면 된다.

2) 언어 메타 파일은 최소 정보만 유지

파일:

  • config/_default/languages.ko.toml
  • config/_default/languages.en.toml
  • config/_default/languages.jp.toml
  • config/_default/languages.cn.toml

변경 내용:

  • 언어별 메타, 로케일, 콘텐츠 경로, 정렬 순서만 남겼다.
  • 메뉴 블록은 제거하고 hugo.toml 의 중앙 메뉴 정의만 사용한다.
  • 기본 언어가 /ko/ 같은 서브디렉터리로 노출되는지는 언어 파일이 아니라 hugo.toml 이 제어한다.

중요한 이유:

  • 언어 설정과 메뉴 설정의 책임이 분리된다.
  • 언어 파일은 콘텐츠 경로와 표시 메타만 책임지게 된다.

3) 기본 언어도 하위 경로를 쓰도록 URL 정책을 고정

파일:

  • config/_default/hugo.toml

변경 내용:

  • defaultContentLanguageInSubdir = true 로 바꿔서 기본 언어도 /ko/ 같은 언어 접두사를 갖도록 정리했다.
  • disableDefaultLanguageRedirect = false 를 명시해 루트(/) 접근 시 기본 언어 서브디렉터리로 안내하는 동작을 유지했다.
  • content/ko, content/en, content/jp, content/cn 구조는 그대로 두고, URL 접두사만 전역 설정으로 통제하게 했다.

중요한 이유:

  • content/ko 로 분리해 두었더라도, 기본 언어는 설정값이 false 면 루트(/)로 노출되는 것이 Hugo 기본 동작이다.
  • 폴더 구조가 잘못된 것이 아니라 URL 정책이 루트 우선으로 되어 있었던 것이다.
  • 이후 사이트가 커져도 언어별 URL 규칙이 흔들리지 않는다.

4) 로케일별 퍼머링크는 front matter 의 slug / url 로 조절

파일:

  • 각 언어의 콘텐츠 파일들

변경 내용:

  • 번역된 페이지는 동일한 translationKey 로 묶고, 필요할 때만 slug 나 url 로 언어별 경로를 분리할 수 있다.
  • 섹션 페이지는 url 중심으로 관리하는 편이 안전하다.
  • 일반 페이지는 slug 로 로케일별 URL 을 개별화할 수 있다.

중요한 이유:

  • 언어별 문서 제목이 같아도 URL 은 독립적으로 제어할 수 있다.
  • 나중에 콘텐츠가 늘어도 하드코딩 없이 경로 정책을 유지할 수 있다.

5) 번역 문자열의 실제 원본을 theme i18n 으로 통합

파일:

  • themes/(0000-0000-0000-0001)/i18n/en.yaml
  • themes/(0000-0000-0000-0001)/i18n/ko.yaml
  • themes/(0000-0000-0000-0001)/i18n/jp.yaml
  • themes/(0000-0000-0000-0001)/i18n/cn.yaml

변경 내용:

  • 프로젝트 루트 i18n/ 은 비워 둔 상태로 정리했다.
  • 텍스트와 메뉴 라벨은 테마 i18n 이 1순위가 되도록 맞췄다.
  • home, blog, categories, tags, about, contact 같은 기본 내비게이션 문자열은 언어별로 교체 가능하게 유지한다.

중요한 이유:

  • 페이지 본문과 UI 문구의 책임이 분리된다.
  • 번역은 콘텐츠, 공통 라벨은 테마로 모여서 유지보수가 쉬워진다.

이번 패스에서 확인한 트리 구조

content/
└─ ko/
   ├─ _index.md
   ├─ about/_index.md
   ├─ blog/
   │  ├─ _index.md
   │  └─ theme-upgrade-lab/
   │     ├─ _index.md
   │     ├─ 00-full-coverage.md
   │     ├─ 01-foundation/
   │     │  ├─ _index.md
   │     │  ├─ design-tokens.md
   │     │  ├─ color-surface.md
   │     │  ├─ layout-spacing.md
   │     │  └─ typography-language.md
   │     ├─ 02-components/
   │     │  ├─ _index.md
   │     │  ├─ controls-cards.md
   │     │  ├─ cta-shortcode.md
   │     │  └─ media-figure.md
   │     ├─ 03-rendering/
   │     │  ├─ _index.md
   │     │  ├─ markdown-rendering.md
   │     │  ├─ shortcode-composition.md
   │     │  └─ edge-cases.md
   │     ├─ 04-architecture/
   │     │  ├─ _index.md
   │     │  ├─ taxonomy-navigation.md
   │     │  └─ bundles-resources/
   │     │     ├─ index.md
   │     │     ├─ cover.svg
   │     │     └─ diagram.svg
   │     ├─ 05-operations/
   │     │  ├─ _index.md
   │     │  ├─ update-log.md
   │     │  ├─ upgrade-summary.md
   │     │  └─ verification-log.md
   │     └─ 06-public-posts/
   │        ├─ _index.md
   │        ├─ 01-productivity-routine.md
   │        ├─ 02-budget-guide.md
   │        ├─ 03-weekend-cleanup.md
   │        └─ 04-travel-checklist.md
   ├─ categories/_index.md
   ├─ contact/_index.md
   └─ tags/_index.md

주의사항

  • 디자인은 페이지 내부에서 고정 수치를 늘리지 말고, theme-vars.css 계층을 먼저 바꿔야 한다.
  • config/_default/params.toml 은 중앙 정책의 원본이지, 개별 페이지 전용 색상표가 아니다.
  • 언어별 콘텐츠는 같은 트리 구조를 유지해야 번역/비교/검증이 쉬워진다.

배포 전 마지막 확인

  • 홈, 소개, 연락, 블로그 목록이 모두 열리는가
  • 토큰 페이지의 색상/간격/폰트/반경이 실제 화면에서 보이는가
  • CTA, figure, collapse, raw HTML, ltr/rtl 이 모두 정상 동작하는가
  • page bundle 리소스가 상대 경로로 깨지지 않는가