Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

gettext(PO 파일)를 사용한 현지화

CSV 형식 <doc_localization_using_spreadsheets>`으로 번역을 가져오는 것 외에도 Godot는 GNU gettext 형식(텍스트 기반 `.po`` 및 컴파일된 .mo)으로 작성된 번역 파일 로드를 지원합니다.

참고

gettext에 대한 소개는 A 빠른 Gettext 튜토리얼 <https://www.labri.fr/perso/fleury/posts/programming/a-quick-gettext-tutorial.html>`_을 확인하세요. C 프로젝트를 염두에 두고 작성되었지만 대부분의 조언은 Godot에도 적용됩니다(``xgettext` 제외).

전체 문서를 보려면 `GNU Gettext <https://www.gnu.org/software/gettext/manual/gettext.html>`_을 참조하세요.

장점

  • gettext는 `Poedit <https://poedit.net/>`_와 같은 텍스트 편집기나 GUI 편집기를 사용하여 편집할 수 있는 표준 형식입니다. 이는 오래된 문자열 표시, 번역되지 않은 문자열 찾기 등 번역가에게 많은 도구를 제공하므로 중요할 수 있습니다.

  • gettext는 Transifex 및 `Weblate <https://weblate.org/>`_와 같은 번역 플랫폼에서 지원되므로 사람들이 현지화에 더 쉽게 협력할 수 있습니다.

  • CSV에 비해 gettext 파일은 Git과 같은 버전 제어 시스템에서 더 잘 작동합니다. 각 로케일에는 자체 메시지 파일이 있기 때문입니다.

  • 여러 줄 문자열은 CSV 파일에 비해 gettext PO 파일에서 편집하는 것이 더 편리합니다.

단점

  • gettext PO 파일은 CSV보다 형식이 더 복잡하고 소프트웨어 현지화를 처음 접하는 사람들이 이해하기 어려울 수 있습니다.

  • 현지화 파일을 관리하는 사람들은 시스템에 gettext 도구를 설치해야 합니다. 그러나 Godot는 텍스트 기반 메시지 파일(.po) 사용을 지원하므로 번역자는 gettext 도구를 설치하지 않고도 작업을 테스트할 수 있습니다.

  • gettext PO 파일은 일반적으로 영어를 기본 언어로 사용합니다. 번역가는 이 기본 언어를 사용하여 다른 언어로 번역합니다. 다른 언어를 기본 언어로 사용할 수도 있지만 이는 일반적이지 않습니다.

gettext 툴 설치하기

메시지 파일 업데이트와 같은 유지 관리 작업을 수행하려면 명령줄 gettext 도구가 필요합니다. 따라서 설치하는 것이 좋습니다.

  • Windows: `이 페이지 <https://mlocati.github.io/articles/gettext-iconv-windows.html>`_에서 설치 프로그램을 다운로드합니다. 모든 아키텍처 및 바이너리 유형(공유 또는 정적)이 작동합니다. 의심스러운 경우 64비트 정적 설치 프로그램을 선택하세요.

  • macOS: brew install gettext 명령과 함께 Homebrew <https://brew.sh/>`_을 사용하거나 ``sudo port install gettext` 명령과 함께 `MacPorts <https://www.macports.org/>`_을 사용하여 gettext를 설치합니다.

  • Linux: 대부분의 배포판에서는 배포판의 패키지 관리자에서 gettext 패키지를 설치합니다.

GUI 도구의 경우 `공식 웹사이트 <https://poedit.net/>`_에서 Poedit를 얻을 수 있습니다. 기본 버전은 오픈 소스이며 MIT 라이선스에 따라 사용할 수 있습니다.

템플릿 위치시키기

편집기를 사용하여 자동 생성

편집기는 지정된 씬 및 GDScript 파일에서 자동으로 PO 템플릿을 생성할 수 있습니다. 이 POT 생성은 tr()``의 선택적 두 번째 인수와 ``tr_n() 메서드를 사용하여 스크립트에서 사용되는 경우 번역 컨텍스트 및 복수화도 지원합니다.

프로젝트 > 프로젝트 설정 > Localization > Template Generation`을 연 다음 :button:`Add… 버튼을 사용하여 지역화 가능한 문자열이 포함된 스크립트 및 프로젝트 장면의 경로를 지정합니다.

프로젝트 설정의 현지화 > 템플릿 생성 탭에서 PO 템플릿 생성

프로젝트 설정`의 :menu:`Localization > Template Generation 탭에서 PO 템플릿 생성

하나 이상의 씬 또는 스크립트를 추가한 후 오른쪽 상단 모서리에 있는 Generate`을 클릭한 다음 ``pot` 파일 확장자로 출력 파일의 경로를 지정합니다. 이 파일은 프로젝트 디렉터리 어디에나 배치할 수 있지만 각 로케일이 자체 파일에 정의되므로 ``locale``와 같은 하위 디렉터리에 보관하는 것이 좋습니다.

번역자를 위한 설명을 추가하거나 GDScript 파일의 PO 템플릿에 일부 문자열이 추가되지 않도록 제외하는 방법은 :ref:`below <doc_localization_using_gettext_gdscript>`를 참조하세요.

그런 다음 :ref:`PO 템플릿에서 메시지 파일 생성 <doc_localization_using_gettext_messages_file>`으로 이동할 수 있습니다.

참고

지역화 가능한 문자열을 변경한 후 또는 새 장면 또는 스크립트를 추가한 후 PO 템플릿을 다시 생성해야 합니다. 그렇지 않으면 새로 추가된 문자열을 현지화할 수 없으며 번역자가 오래된 문자열에 대한 번역을 업데이트할 수 없습니다.

벡터 보간

자동 생성 접근 방식이 요구 사항에 맞지 않는 경우 텍스트 편집기에서 직접 PO 템플릿을 만들 수 있습니다. 이 파일은 프로젝트 디렉터리 어디에나 배치할 수 있지만 각 로케일이 자체 파일에 정의되므로 하위 디렉터리에 보관하는 것이 좋습니다.

만들기 프로젝트 디렉터리에 ``locale``라는 디렉터리가 있습니다. 이 디렉터리에 다음 내용이 포함된 ``messages.pot``라는 파일을 저장합니다.

# Don't remove the two lines below, they're required for gettext to work correctly.
msgid ""
msgstr ""

# Example of a regular string.
msgid "Hello world!"
msgstr ""

# Example of a string with pluralization.
msgid "There is %d apple."
msgid_plural "There are %d apples."
msgstr[0] ""
msgstr[1] ""

# Example of a string with a translation context.
msgctxt "Actions"
msgid "Close"
msgstr ""

gettext의 메시지는 msgid 및 msgstr 쌍으로 구성됩니다. ``msgid``는 소스 문자열(일반적으로 영어)이고, ``msgstr``는 번역된 문자열입니다.

경고

PO 템플릿 파일(.pot)의 msgstr 값은 항상 비어 있어야 합니다. 대신 생성된 .po 파일에서 현지화가 수행됩니다.

PO 템플릿에서 메시지 파일 생성

msginit 명령은 PO 템플릿을 메시지 파일로 변환하는 데 사용됩니다. 예를 들어 프랑스어 지역화 파일을 생성하려면 locale 디렉터리에 있는 동안 다음 명령을 사용합니다.

msginit --no-translator --input=messages.pot --locale=fr

위 명령은 PO 템플릿과 동일한 디렉터리에 ``fr.po``라는 파일을 생성합니다.

또는 Poedit를 사용하여 그래픽으로 수행하거나 선택한 웹 플랫폼에 POT 파일을 업로드하여 수행할 수 있습니다.

Godot에서 메시지 파일을 불러오기

메시지 파일을 프로젝트의 번역으로 등록하려면 프로젝트 설정`을 열고 :menu:`Localization > Translations`으로 이동하여 :button:`Add…`을 클릭한 다음 파일 대화 상자에서 `.po`` 또는 .mo 파일을 선택합니다. 로케일은 메시지 파일의 "Language: <code>\n" 속성에서 유추됩니다.

참고

Godot에서 번역 가져오기 및 테스트에 대한 자세한 내용은 :ref:`doc_internationalizing_games`를 참조하세요.

PO 템플릿을 따르도록 메시지 파일 업데이트

PO 템플릿을 업데이트한 후에는 PO 템플릿에 더 이상 존재하지 않는 문자열을 제거하는 동시에 새 문자열을 포함하도록 메시지 파일을 업데이트해야 합니다. 이 작업은 msgmerge 도구를 사용하여 자동으로 수행할 수 있습니다.

# The order matters: specify the message file *then* the PO template!
msgmerge --update --backup=none fr.po messages.pot

원본 메시지 파일(이 예에서는 fr.po~``로 저장됨)의 백업을 유지하려면 ``--backup=none 인수를 제거하세요.

참고

msgmerge``를 실행한 후 소스 언어에서 수정된 문자열은 ``.po 파일에서 문자열 앞에 "퍼지" 주석이 추가됩니다. 이 주석은 번역이 업데이트될 때까지 부정확할 가능성이 높으므로 새 소스 문자열과 일치하도록 번역을 업데이트해야 함을 나타냅니다.

"퍼지" 주석이 있는 문자열은 번역이 업데이트되고 "퍼지" 주석이 제거될 때까지 Godot가 읽지 않습니다.

PO 파일 또는 템플릿의 유효성 확인

gettext 파일의 구문이 유효한지 확인할 수 있습니다.

Poeditor로 열면 구문 오류가 있는 경우 적절한 경고가 표시됩니다. 아래 gettext 명령을 실행하여 확인할 수도 있습니다.

msgfmt fr.po --check

구문 오류나 경고가 있으면 콘솔에 표시됩니다. 그렇지 않으면 ``msgfmt``는 아무것도 출력하지 않습니다.

바이너리 MO 파일 사용(대규모 프로젝트에만 유용함)

번역할 문자열이 수천 개 이상인 대규모 프로젝트의 경우 텍스트 기반 PO 파일 대신 바이너리(컴파일된) MO 메시지 파일을 사용하는 것이 좋습니다. 바이너리 MO 파일은 동등한 PO 파일보다 더 작고 읽기가 더 빠릅니다.

아래 명령을 사용하여 MO 파일을 생성할 수 있습니다.

msgfmt fr.po --no-hash -o fr.mo

PO 파일이 유효한 경우 이 명령은 PO 파일 외에 fr.mo 파일을 생성합니다. 이 MO 파일은 위에서 설명한 대로 Godot에 로드될 수 있습니다.

나중에 번역을 업데이트할 수 있도록 원본 PO 파일을 버전 관리에 보관해야 합니다. 원본 PO 파일을 잃어버렸고 MO 파일을 텍스트 기반 PO 파일로 디컴파일하려는 경우 다음을 수행할 수 있습니다.

msgunfmt fr.mo > fr.po

디컴파일된 파일에는 주석이나 퍼지 문자열이 포함되지 않습니다. 이러한 내용은 애초에 MO 파일에서 컴파일되지 않기 때문입니다.

텍스처를 각각 내보내기

내장된 `편집기 플러그인 <https://github.com/godotengine/godot/blob/master/modules/gdscript/editor/gdscript_translation_parser_plugin.h>`_은 소스 코드의 다양한 패턴을 인식하여 다음을 포함하되 이에 국한되지 않는 GDScript 파일에서 현지화 가능한 문자열을 추출합니다.

  • tr(), tr_n(), atr() 및 atr_n() 호출;

  • text, placeholder_text 및 tooltip_text 속성 할당;

  • add_tab(), add_item(), set_tab_title() 및 기타 통화;

  • FileDialog 필터는 ``"*.png ; PNG Images"``와 같습니다.

참고

인수 또는 오른쪽 피연산자는 상수 문자열이어야 합니다. 그렇지 않으면 플러그인이 표현식을 평가할 수 없으며 이를 무시합니다.

플러그인이 불필요한 문자열을 추출하는 경우 NO_TRANSLATE 주석을 사용하여 무시할 수 있습니다. TRANSLATORS: 설명을 사용하여 번역가에게 추가 정보를 제공할 수도 있습니다. 이러한 주석은 인식된 패턴과 같은 줄에 있거나 그 앞에 배치되어야 합니다.

$CharacterName.text = "???" # NO_TRANSLATE

# NO_TRANSLATE: Language name.
$TabContainer.set_tab_title(0, "Python")

item.text = "Tool" # TRANSLATORS: Up to 10 characters.

# TRANSLATORS: This is a reference to Lewis Carroll's poem "Jabberwocky",
# make sure to keep this as it is important to the plot.
say(tr("He took his vorpal sword in hand. The end?"))

RigidBody2D 사용하기

context 매개변수는 번역이 사용되는 상황을 구별하거나 다의어 단어(여러 의미를 가진 단어)를 구별하는 데 사용할 수 있습니다.

예를 들면:

tr("Start", "Main Menu")
tr("End", "Main Menu")
tr("Shop", "Main Menu")
tr("Shop", "In Game")

gettext PO 파일에서 컨텍스트가 있는 문자열은 다음과 같이 정의될 수 있습니다.

# Example of a string with a translation context.
msgctxt "Main Menu"
msgid "Shop"
msgstr ""

# A different source string that is identical, but with a different context.
msgctxt "In Game"
msgid "Shop"
msgstr ""

PCK 파일 생성하기

어느 정도 시간이 지나면 게임에 새 콘텐츠가 추가되고 번역해야 할 새 문자열이 생길 것입니다. 이런 일이 발생하면 새 문자열을 포함하도록 기존 PO 파일을 업데이트해야 합니다.

먼저 기존 문자열과 새로 추가된 문자열을 모두 포함하는 새 POT 파일을 생성합니다. 그런 다음 기존 PO 파일을 새 POT 파일과 병합합니다. 이를 수행하는 방법에는 두 가지가 있습니다.

  • gettext 편집기를 사용하면 POT 파일에서 PO 파일을 업데이트하는 옵션이 있어야 합니다.

  • gettext msgmerge 도구를 사용합니다.

# The order matters: specify the message file *then* the PO template!
msgmerge --update --backup=none fr.po messages.pot

원본 메시지 파일(이 예에서는 fr.po~``로 저장됨)의 백업을 유지하려면 ``--backup=none 인수를 제거하세요.

버전 관리 시스템

처리해야 할 추가 파일 형식이 있는 경우 사용자 정의 플러그인을 작성하여 사용자 정의 파일에서 문자열을 구문 분석하고 추출할 수 있습니다. 이 사용자 정의 플러그인은 **Generate POT**을 누르면 문자열을 추출하고 POT 파일에 씁니다. 번역 파서 플러그인을 생성하는 방법에 대한 자세한 내용은 :ref:`EditorTranslationParserPlugin <class_EditorTranslationParserPlugin>`을 참조하세요.