-
Salesforce 번역 설정, Translation Workbench 실전 가이드Setup 2026. 7. 9. 15:49반응형
Salesforce를 한국어로 운영하다 보면 반드시 한 번은 마주치는 작업이 있습니다. 커스텀 오브젝트나 커스텀 필드를 만들고 나면, 레이블이 영어 또는 개발자가 입력한 이름 그대로 화면에 노출됩니다. 이를 한국어로 바꾸는 데 사용하는 것이 Translation Workbench입니다.
설정 화면에서 직접 한 건씩 입력할 수도 있지만, 레이블 수가 많다면 파일로 일괄 내보내기(Export) → 번역 작업 → 가져오기(Import)하는 방식이 훨씬 효율적입니다. 그런데 이 파일 기반 작업 과정에서 예상치 못한 오류가 꽤 자주 나옵니다. 이번 글에서는 Translation Workbench의 기본 흐름과 함께, 실제로 자주 마주치는 문제와 해결 방법을 정리해보겠습니다.
Translation Workbench 활성화부터
가장 먼저 할 일은 Translation Workbench 기능을 켜는 것입니다. Setup → Translation Workbench → Translation Settings에서 활성화할 수 있습니다. 활성화하면 지원할 언어를 추가하고, 각 언어별 번역 담당자를 지정할 수 있습니다.
한국어를 추가하려면 지원 언어 목록에서 Korean(한국어)을 선택하면 됩니다. 활성화 후에는 Setup의 각 항목에 번역 탭이 생기고, 해당 탭에서 오브젝트·필드·픽리스트 값 등의 한국어 번역을 직접 입력할 수 있습니다.
파일 기반 번역 작업 흐름
레이블이 수백 개 이상이라면 화면에서 하나씩 입력하는 것은 비효율적입니다. Salesforce는 번역 파일을 내보내고 가져오는 두 가지 파일 형식을 지원합니다.
.xlf (XLIFF 형식): XML 기반 번역 표준 포맷입니다. 커스텀 오브젝트, 필드 레이블, 픽리스트 값, 버튼 레이블 등 대부분의 메타데이터 번역에 사용됩니다.
.stf (Salesforce Translation Format): Salesforce 자체 포맷으로, 일부 특수 항목(예: 표준 오브젝트 레이블, 특정 UI 텍스트)의 번역에 사용됩니다.
일반적인 흐름은 이렇습니다.
- Translation Workbench → Export에서 번역 파일 내보내기 (언어와 오브젝트 범위 선택)
- 내려받은 .xlf 파일을 열어 번역 작업 진행
- Translation Workbench → Import에서 번역 완료된 파일 올리기
.xlf 파일 구조 이해하기
.xlf 파일을 처음 열면 낯선 XML 구조가 펼쳐집니다. 핵심만 보면 이렇습니다.
xml<trans-unit id="..."> <source>원본 레이블 (영문)</source> <target>번역할 텍스트 입력 위치</target> </trans-unit><source> 태그에는 원본 레이블이 들어 있고, <target> 태그 안에 번역된 텍스트를 입력하면 됩니다. 번역 작업은 <target> 값을 채우는 것이 전부입니다.
실제로 자주 마주치는 문제들
파일 기반 번역이 편리한 만큼, 가져오기 단계에서 오류가 나면 이유를 찾기가 까다롭습니다. 실무에서 자주 발생하는 문제 유형을 정리했습니다.
1. <target> 태그가 비어 있으면 import 오류가 난다
번역 작업을 하다 보면 일부 항목은 번역이 불필요해서 <target></target> 또는 <target/> 형태로 비워두는 경우가 있습니다. 그런데 Salesforce는 이 빈 <target> 태그를 오류로 처리하는 경우가 있습니다. 특히 파일 안에 빈 target이 많을수록 import 자체가 실패하거나, 일부 항목이 누락되는 현상이 발생합니다.
해결 방법은 번역이 필요 없는 항목은 <target> 태그 자체를 삭제하거나, 원본과 동일한 값을 그대로 입력해두는 것입니다. 빈 태그를 남겨두지 않는 것이 안전합니다.
2. 파일 인코딩 문제
.xlf 파일을 Excel이나 일반 텍스트 편집기로 열어서 저장하면 인코딩이 변경될 수 있습니다. 특히 Windows 환경에서 메모장으로 저장하면 BOM(Byte Order Mark)이 추가되거나 UTF-8이 아닌 다른 인코딩으로 저장되는 경우가 있습니다. 이렇게 저장된 파일을 Salesforce에 올리면 특수문자나 한국어가 깨지거나 import 자체가 실패합니다.
번역 파일은 반드시 UTF-8(BOM 없음) 인코딩으로 저장해야 합니다. VS Code, Notepad++, Sublime Text 등에서 인코딩을 명시적으로 지정해서 저장하는 습관이 필요합니다.
3. .stf 파일 업로드 실패
.stf 형식의 파일은 .xlf보다 덜 사용되지만, 표준 오브젝트 관련 번역이나 특수 UI 항목을 다룰 때 필요합니다. 그런데 .stf 파일은 업로드 시 Salesforce가 형식을 더 엄격하게 검증하는 경우가 있어서, 파일 내용이 조금이라도 규격에서 벗어나면 오류 없이 업로드가 완료되는 것처럼 보여도 실제로는 반영이 안 되는 경우가 있습니다.
.stf 작업 시에는 반드시 업로드 후 실제 화면에서 번역이 적용되었는지 직접 확인하는 것이 좋습니다. 업로드 성공 메시지만으로는 실제 반영 여부를 보장할 수 없습니다.
4. 번역 반영이 되었는데 화면에 안 보인다
파일 import가 성공했는데 실제 Salesforce 화면에서 번역이 보이지 않는 경우가 있습니다. 원인은 주로 두 가지입니다.
첫 번째는 사용자의 언어 설정입니다. 개인 설정(Personal Settings)에서 Language가 한국어로 되어 있어야 번역이 적용된 화면이 보입니다. 조직 기본 언어와 개인 언어 설정이 다를 수 있다는 점을 염두에 두어야 합니다.
두 번째는 번역 대상이 커스텀 항목이 아닌 경우입니다. 표준 오브젝트의 표준 필드 레이블은 Translation Workbench로 변경되지 않고, Salesforce가 자체적으로 번역을 제공합니다. 커스텀 레이블과 표준 레이블을 혼동하면 번역 작업을 해도 화면에 반영되지 않는 상황이 생깁니다.
픽리스트 값 번역 주의사항
픽리스트(Picklist) 값도 Translation Workbench에서 번역할 수 있습니다. 단, 픽리스트 값의 번역은 값(Value) 자체가 아니라 레이블(Label) 만 바뀝니다. 데이터베이스에 저장되는 실제 값은 영문 원본 그대로입니다.
이 원칙을 이해하지 못하면, "화면에서는 한국어로 보이는데 SOQL이나 보고서 필터에서는 영문으로 써야 하는" 상황이 생깁니다. 특히 Flow나 Apex에서 픽리스트 값을 조건으로 비교할 때는 항상 번역 이전의 원본 값(API Value)을 기준으로 작성해야 합니다.
번역 작업 효율화 팁
번역 파일이 많아지면 관리가 복잡해집니다. 실무에서 도움이 됐던 방법들을 공유합니다.
export 범위를 좁게 가져간다. 전체 오브젝트를 한꺼번에 export하면 파일이 너무 커져서 작업이 불편합니다. 작업 단위별로 오브젝트를 선택해서 내보내는 것이 관리하기 좋습니다.
번역 완료 항목과 미완료 항목을 구분해둔다. 파일 안에서 <target> 값이 채워진 항목과 비어 있는 항목을 구분해두면, 어느 항목까지 번역이 완료됐는지 파악하기 쉽습니다.
변경 이력을 남긴다. 번역 파일은 버전 관리가 되지 않기 때문에, 작업 날짜나 버전 정보를 파일명에 포함해서 보관해두는 것이 좋습니다. 나중에 "이전 번역이 어떻게 되어 있었는지" 를 확인해야 하는 상황이 생각보다 자주 옵니다.
마무리
Translation Workbench는 Salesforce를 다국어 환경에서 운영할 때 핵심 도구지만, 파일 기반 작업 과정에서 놓치기 쉬운 함정이 여럿 있습니다. 빈 <target> 태그, 인코딩 문제, .stf 반영 확인, 픽리스트 원본 값 유지 원칙 등 이 포인트들만 알아두어도 번역 작업 중 마주치는 대부분의 문제를 사전에 예방할 수 있습니다.
번역 작업은 화려하지 않지만, 사용자가 매일 마주치는 화면의 품질을 결정하는 중요한 작업입니다.
반응형