모드 내 다국어 — lang/<locale>.json

Minecraft는 처음부터 다국어를 지원하도록 설계되었습니다. 아이템 이름, 블록 이름, GUI 텍스트, 사망 메시지까지 모두 lang 파일 하나로 관리합니다. 모드도 같은 방식을 따릅니다. 이 챕터에서는 lang 파일의 구조와 위치, Component.translatable()로 텍스트를 참조하는 방법을 배웁니다.

💡 사이트 i18n vs 모드 i18n

• 사이트 i18n (messages/{ko,en}.json + next-intl): 이 학습 문서 자체의 UI 번역
• 모드 i18n (assets/examplemod/lang/*.json + Minecraft): 모드 안의 게임 텍스트 번역

둘은 완전히 별개 시스템입니다. 혼동하지 마세요.

1. lang 파일 위치

lang 파일은 모드의 리소스 폴더 안에 있습니다.

src/main/resources/
└── assets/
    └── examplemod/          ← modId
        └── lang/
            ├── en_us.json   ← 영어 (필수, 기본값)
            └── ko_kr.json   ← 한국어 (선택)

en_us.json은 반드시 있어야 합니다. Minecraft는 현재 언어에 해당하는 lang 파일이 없으면 en_us.json을 폴백으로 사용합니다. 한국어만 제공하고 영어를 빠뜨리면, 영어 사용자에게 raw 키가 그대로 보입니다.

2. lang 파일 형식

JSON 객체입니다. 키는 번역 키, 값은 표시할 텍스트입니다.

{
  "item.examplemod.example_item": "예시 아이템",
  "block.examplemod.example_block": "예시 블록",
  "itemGroup.examplemod": "예시 모드 탭",
  "death.attack.example": "%1$s이(가) 예시로 사망했습니다"
}

examplemod-template-26.1.2의 실제 en_us.json은 이렇게 생겼습니다.

{
  "itemGroup.examplemod": "Example Mod Tab",
  "block.examplemod.example_block": "Example Block",
  "item.examplemod.example_item": "Example Item",
 
  "examplemod.configuration.title": "Example Mod Configs",
  "examplemod.configuration.section.examplemod.common.toml": "Example Mod Configs",
  "examplemod.configuration.section.examplemod.common.toml.title": "Example Mod Configs",
  "examplemod.configuration.items": "Item List",
  "examplemod.configuration.logDirtBlock": "Log Dirt Block",
  "examplemod.configuration.magicNumberIntroduction": "Magic Number Text",
  "examplemod.configuration.magicNumber": "Magic Number"
}

아이템·블록 이름뿐 아니라 설정 화면 레이블도 lang 파일로 관리하는 것을 볼 수 있습니다.

3. 키 컨벤션

Vanilla Minecraft의 패턴을 그대로 따릅니다. 일관성이 중요합니다.

<modId>는 항상 소문자 + 언더스코어. <itemId>는 레지스트리에 등록할 때 쓴 이름과 동일하게 맞춥니다.

4. Component.translatable() 사용

Java 코드에서 번역 키를 참조할 때는 Component.translatable()을 씁니다.

// 번역 키로 Component 생성
Component name = Component.translatable("item.examplemod.example_item");
 
// 게임이 현재 언어에 맞는 lang 파일에서 값을 조회합니다.
// 한국어 설정이면 ko_kr.json, 영어 설정이면 en_us.json을 읽습니다.
// 키가 없으면 raw 키 그대로 표시 — 크래시는 발생하지 않습니다.

아이템·블록 등록 시 getDescriptionId()가 자동으로 번역 키를 반환하므로, 대부분의 경우 직접 호출할 필요는 없습니다. 직접 쓰는 경우는 주로 명령어 피드백이나 GUI 텍스트입니다.

// 명령어 실행 결과 메시지
context.getSource().sendSuccess(
    () -> Component.translatable("commands.examplemod.hello"),
    false
);
 
// 포맷 인수 전달 (사망 메시지 등)
Component death = Component.translatable(
    "death.attack.example",
    player.getDisplayName()
);
// lang: "death.attack.example": "%1$s이(가) 예시로 사망했습니다"
// 결과: "플레이어이(가) 예시로 사망했습니다"

5. ko_kr.json 추가하기

en_us.json과 같은 위치에 ko_kr.json을 만들고 같은 키로 한국어 값을 씁니다.

src/main/resources/assets/examplemod/lang/
├── en_us.json
└── ko_kr.json   ← 새로 추가

{
  "itemGroup.examplemod": "예시 모드 탭",
  "block.examplemod.example_block": "예시 블록",
  "item.examplemod.example_item": "예시 아이템",
 
  "examplemod.configuration.title": "예시 모드 설정",
  "examplemod.configuration.items": "아이템 목록",
  "examplemod.configuration.logDirtBlock": "흙 블록 로그",
  "examplemod.configuration.magicNumberIntroduction": "마법 숫자 설명",
  "examplemod.configuration.magicNumber": "마법 숫자"
}

ko_kr.json에 없는 키는 자동으로 en_us.json에서 폴백됩니다. 모든 키를 번역하지 않아도 됩니다.

6. 인게임 언어 변경

게임 내에서 언어를 바꾸면 lang 파일이 즉시 교체됩니다.

1. Options (설정) 버튼 클릭
2. Language... (언어) 선택
3. 목록에서 한국어 찾아 선택
4. Done 클릭

재시작 없이 바로 적용됩니다. 모드 아이템 이름, 탭 이름, 설정 레이블이 모두 ko_kr.json 값으로 바뀝니다.

인게임 언어 변경 화면은 04-run-client 챕터의 Minecraft 실행 화면을 참조하세요.

7. 안티패턴

⚠️ 하드코딩 영어 텍스트

// 하드코딩 — 다국어 안 됨
player.sendSystemMessage(Component.literal("Hello"));
 
// translatable — 자동 다국어
player.sendSystemMessage(Component.translatable("commands.examplemod.hello"));

Component.literal()은 lang 파일을 전혀 참조하지 않습니다. 항상 그 문자열 그대로 표시됩니다. 플레이어에게 보이는 텍스트는 반드시 Component.translatable()을 쓰세요.

키 누락 시: 게임이 raw 키를 표시합니다 ("commands.examplemod.hello" 그대로). 크래시는 발생하지 않으므로, 빌드 후 인게임에서 raw 키가 보이면 lang 파일에 해당 키가 빠진 것입니다.

정리

다음 챕터에서는 아이템에 커스텀 동작을 추가하는 방법을 다룹니다.