WordPress에 번역이 표시되지 않는 이유 (문제 해결 가이드)

WordPress 개발에서 "조용한 실패"보다 더 실망스러운 것은 없습니다.

당신은 모든 것을 올바르게 했습니다. .po 파일을 번역했습니다. .mo 파일로 컴파일했습니다. FTP를 통해 서버에 업로드했습니다. 캐시를 지웠습니다.

페이지를 새로 고치고 스페인어, 프랑스어 또는 독일어가 표시될 것으로 예상합니다. 대신... 영어가 보입니다.

오류 메시지도 없고 흰색 화면도 없습니다. 고집스럽고 번역되지 않은 텍스트뿐입니다. 머리카락을 쥐어뜯기 전에 이 가이드를 읽어보세요. 다음은 WordPress에서 번역이 로드되지 않는 가장 일반적인 5가지 이유와 해결 방법입니다.

1. 파일 이름을 잘못 지정하고 있습니다

WordPress는 파일 이름 지정에 대해 매우 엄격합니다. 한 문자라도 놓치면 파일을 로드하지 않습니다.

표준 형식은 {text-domain}-{locale}.mo입니다.

• 텍스트 도메인 (Text Domain): 테마 또는 플러그인의 고유 ID입니다 (예: woocommerce, twentytwentyfour, my-custom-plugin).
• 로케일 (Locale): WP 로케일 코드 (예: 스페인 스페인어의 경우 es_ES, 프랑스어의 경우 fr_FR).

일반적인 실수:

• 파일 이름을 es_ES.mo로만 지정 (이것은 플러그인이 아닌 전역 WordPress 코어 파일에서만 작동합니다).
• 잘못된 대시 사용: my-plugin-es_ES.mo (하이픈) 대신 my_plugin_es_ES.mo (밑줄).
• 텍스트 도메인 추측. 플러그인의 코드 (style.css 헤더 또는 load_plugin_textdomain 함수)를 확인하여 정확한 슬러그를 찾아야 합니다.

2. 파일을 잘못된 폴더에 넣었습니다

파일을 업로드하는 위치는 이름을 지정하는 방법만큼 중요합니다. WordPress는 특정 순서로 특정 디렉토리를 찾습니다.

• "안전한" 시스템 폴더: /wp-content/languages/plugins/ 또는 /wp-content/languages/themes/.
  • 장점: 플러그인 업데이트로부터 안전합니다.
  • 단점: 파일 이름을 textdomain-locale.mo로 지정해야 합니다.
• 작성자 폴더: /wp-content/plugins/plugin-name/languages/.
  • 장점: 찾기 쉽습니다.
  • 단점: 위험. 플러그인을 업데이트하면 이 폴더가 완전히 지워집니다. 번역이 사라집니다.

모범 사례: 업데이트 중 데이터 손실을 방지하려면 항상 사용자 지정 .mo 파일을 전역 /wp-content/languages/ 디렉토리에 넣으십시오.

3. "조용한 살인자": .po 파일의 구문 손상

이것은 디버그하기 가장 어려운 문제이며 일반적인 AI 번역 도구에서 자주 발생합니다.

WordPress는 .po 텍스트 파일에서 컴파일된 이진 .mo 파일을 읽습니다. .po 파일에 구문 오류가 포함된 경우 .mo 파일이 생성될 수 있지만 내부적으로 "손상"됩니다.

어떻게 이런 일이 발생합니까? 번역가(사람 또는 AI)가 Gettext 서식을 엉망으로 만들면 문자열이 유효하지 않게 됩니다.

• 예: 닫는 따옴표 " 누락.
• 예: 변수 깨기 (%s를 % s로 변경).
• 예: msgid_plural 카운트 엉망으로 만들기.

WordPress가 .mo 파일에서 손상된 항목을 발견하면 종종 건너뛰거나 파일 읽기를 완전히 중지하고 원래 영어로 돌아갑니다.

4. 컴파일하는 것을 잊었습니다 (.po vs .mo)

WordPress는 .po 파일을 직접 읽을 수 없습니다. 이것은 흔한 오해입니다.

• .po = 사람이 읽을 수 있음 (Portable Object).
• .mo = 기계가 읽을 수 있음 (Machine Object).

my-theme-es_ES.po 파일을 업로드했지만 일치하는 .mo 파일을 생성하는 것을 잊은 경우 아무 일도 일어나지 않습니다. 컴파일해야 합니다.

5. 캐싱 (일반적인 용의자)

캐싱 플러그인(WP Rocket, LiteSpeed) 또는 서버 측 캐싱(Varnish, Redis)을 사용하는 경우 사이트에서 번역을 업로드하기 전의 캐시된 HTML 버전을 제공하고 있을 수 있습니다.

해결: 브라우저 캐시 및 개체 캐시를 포함한 모든 캐시를 지웁니다.

궁극적인 해결책: 처음부터 유효한 파일

파일 경로 및 이름 문제를 해결하는 것은 쉽습니다. 손상된 구문 (이유 #3) 문제를 해결하는 것은 악몽입니다.

코드 변수를 깨뜨리거나 Gettext 구조를 손상시키는 도구를 사용하는 경우 파일 자체가 "중독"되었다는 사실을 깨닫지 못한 채 파일이 작동하지 않는 이유를 궁금해하며 몇 시간을 보낼 것입니다.

이것이 우리가 SimplePoTranslate를 구축한 이유입니다.

• 구문 잠금: 다운로드하기 전에 모든 단일 문자열이 구문적으로 유효한지 확인합니다. %s와 같은 변수를 잠가 깨지지 않도록 합니다.
• 완벽한 서식: 100% 작동하는 .mo 파일로 컴파일되는 깨끗하고 표준적인 .po 파일을 생성합니다.
• 플러그인 필요 없음: 파일을 다운로드하면 작동한다는 것을 알 수 있습니다. 올바른 폴더에 업로드하기만 하면 됩니다.

번역이 보이지 않는 이유를 추측하지 마십시오. 신뢰할 수 있는 파일로 시작하십시오.

골치 아픈 일 없이 번역할 준비가 되셨습니까? SimplePoTranslate.com에서 무료로 시작하세요