Odoo 다국어 번역 필드 완전 정복 가이드

많은 기업이 여러 언어로 업무를 처리합니다. 예를 들어 프랑스어 영업팀, 독일 창고, 스페인어 고객 포털 같은 환경에서는 동일한 레코드가 사용자마다 다른 언어로 보여져야 합니다. Odoo의 번역 가능한 필드는 바로 이런 요구를 충족시키기 위해 고안된 기능입니다.

번역 가능한 필드는 언어별로 각각의 값을 보관합니다. 같은 제품 레코드를 프랑스어 사용자가 열면 프랑스어 이름을, 독일어 사용자가 열면 독일어 이름을 보게 됩니다. 데이터베이스에는 하나의 레코드만 있지만, 보는 사람의 언어에 따라 다른 표현을 제공합니다.

이 가이드는 Odoo ORM 내부에서 번역 필드가 어떻게 동작하는지, 필드를 어떻게 만들고 관리하는지, 그리고 실제 비즈니스에서 언제 이 기능이 유용한지를 설명합니다.

Odoo에서 '번역 가능한 필드'란 무엇인가요?

번역 가능한 필드는 사람 읽을 수 있는 텍스트를 언어별로 보관할 수 있는 데이터 모델 필드입니다. 사용자는 별도 설정 없이 자신의 언어로 된 값을 보게 되며, 번역 처리가 투명하게 이루어집니다.

Odoo에서 번역을 지원하는 필드 유형은 다음과 같습니다:

• Char: 한 줄짜리 짧은 텍스트(예: 제품명, 카테고리 라벨, 직책)
• Text: 여러 줄 텍스트(예: 상세 설명, 노트)
• Html: HTML 마크업이 포함된 리치 텍스트(예: 웹사이트 콘텐츠, 이메일 템플릿 본문)

숫자형, 날짜형, Many2one 같은 관계 필드, 불리언 필드는 번역 대상이 아닙니다. 번역은 사람이 읽는 텍스트에만 적용됩니다.

UI에서의 동작 방식

편집 모드에서 번역 가능한 필드는 필드 옆에 작은 언어 깃발 아이콘이 표시됩니다. 이 아이콘을 클릭하면 설치된 각 언어에 대한 값을 입력하거나 관리할 수 있는 다이얼로그가 열립니다.

읽기 모드에서는 사용자가 자신의 언어에 맞는 값만 보게 됩니다. 해당 언어의 번역이 없다면 빈 값 대신 보통 데이터베이스의 기본 언어(대개 영어) 값을 표시해 사용자가 의미 없는 빈칸을 보지 않게 합니다.

번역 가능한 필드의 작동 원리

번역 필드의 내부 동작을 이해하면 언제 해당 기능을 적용하고 어떻게 대규모로 관리할지 더 현명한 결정을 내릴 수 있습니다.

translate=True 파라미터

Odoo ORM에서 필드를 번역 가능하게 만들려면 필드 정의에 translate=True를 추가하면 됩니다. 예를 들어 커스텀 Char 필드에 다음처럼 설정합니다:

from odoo import models, fields

class ProductTemplate(models.Model):
    _inherit = 'product.template'

    x_marketing_tagline = fields.Char(
        string='Marketing Tagline',
        translate=True
    )

이 한 줄의 설정으로 Odoo는 활성 언어에 따라 서로 다른 값을 저장하고 불러오도록 처리합니다. Odoo 프레임워크의 간결하고 강력한 기능 중 하나입니다.

번역 데이터의 저장 방식

번역 데이터 저장 방식은 Odoo 버전에 따라 달라졌습니다:

• Odoo 15 및 이전: 번역 값은 별도 ir.translation 테이블에 행 단위로 저장됐습니다. 각 번역은 모델, 필드명, 레코드 ID, 언어 코드에 연결된 개별 행이었습니다.
• Odoo 16 이상: 번역 값은 모델의 자체 테이블 안에 JSONB 컬럼으로 저장됩니다. 예를 들어 name 필드는 {"en_US": "Laptop Stand", "fr_FR": "Support pour ordinateur portable", "de_DE": "Laptopständer"} 같은 JSON으로 관리됩니다.

Odoo 16에서 JSONB로 전환된 것은 성능과 확장성 측면에서 큰 개선입니다. 별도 번역 테이블과의 조인 비용을 줄이고, 특히 레코드가 많은 모델에서 쿼리 속도가 훨씬 빨라집니다.

언어 컨텍스트는 어떻게 동작하나

Odoo가 번역 필드를 읽을 때는 항상 컨텍스트의 활성 언어를 확인합니다. 예를 들어 프랑스어로 로그인한 사용자는 ORM이 자동으로 프랑스어 값을 가져오게 됩니다. API 호출 시에는 컨텍스트에 언어를 명시하여 제어할 수 있습니다:

models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'product.template', 'read',
    [[product_id]],
    {'fields': ['name'], 'context': {'lang': 'fr_FR'}}
)

통합 작업이나 데이터 익스포트 스크립트를 만들 때는 항상 올바른 언어를 컨텍스트에 전달해 정확한 번역 값을 가져오도록 해야 합니다.

translate 파라미터에 호출 가능 객체 전달하기

translate 파라미터는 고급 사용을 위해 호출 가능한(callable) 객체도 받을 수 있습니다. 흔히 translate=_ 처럼 모듈 내부의 정적 문자열(예: 선택 항목 라벨)을 번역용으로 표시할 때 사용되며, 이는 레코드 수준의 번역과는 별개로 모듈 문자열을 번역하기 위한 표준 워크플로우에 쓰입니다.

폴백 동작

활성 언어에 해당하는 번역이 없으면 Odoo는 빈 값을 반환하지 않고 기본 언어 값으로 폴백합니다(대개 영어). 이 덕분에 부분적으로만 번역된 환경에서도 사용자는 의미 있는 정보를 항상 볼 수 있습니다.

비즈니스 적용 사례

번역 가능한 필드는 단순한 기술적 기능을 넘어 다국적 운영에서 실제 문제를 해결합니다. 자주 등장하는 다섯 가지 활용 사례는 다음과 같습니다.

1. 전자상거래: 다국어 제품명·설명 제공

Odoo 쇼핑몰에서 제품명을 현지 언어로 보여주면 고객 경험이 훨씬 좋아집니다. product.template의 name, description 같은 필드는 기본적으로 번역 가능하므로 단일 카탈로그로 여러 언어의 제품명, 판매 문구, 사양을 관리할 수 있습니다.

프랑스 사이트 방문자는 프랑스어 제품명과 설명을 보고, 재고·가격·규칙은 동일하게 유지됩니다. 다만 화면에 표시되는 텍스트만 해당 언어로 바뀝니다.

2. 다국적 기업의 이메일 템플릿

Odoo의 이메일 템플릿 본문은 Html 타입의 번역 가능한 필드를 사용합니다. 주문 확인 이메일을 독일 고객에게 보낼 때 독일어 버전의 템플릿 본문이 설정되어 있으면 자동으로 해당 내용을 사용합니다.

이렇게 하면 시장별로 별도의 템플릿을 만들 필요 없이 하나의 템플릿으로 모든 언어를 깔끔하게 처리할 수 있습니다.

3. 웹페이지와 블로그 콘텐츠

Odoo 웹사이트의 페이지 콘텐츠는 Html 번역 필드를 사용합니다. 다국어 사이트를 활성화하면 에디터가 같은 페이지의 언어별 텍스트를 각각 관리할 수 있어, 별도 플러그인 없이도 다국어 사이트를 운영할 수 있습니다.

SEO 측면에서도 각 언어 버전에 고유한 메타 타이틀과 설명을 둘 수 있어 지역별 검색 결과에 노출되기 유리합니다.

4. 국제 조직을 위한 선택 목록 라벨

Selection 필드의 옵션 라벨은 코드에서 표준 번역 함수 _로 표시할 수 있습니다. 예를 들어 영어 사용자는 "In Progress", "On Hold", "Completed"를 보지만 다른 언어 사용자에게는 해당 언어로 된 라벨이 보입니다.

이 기능은 인사·프로젝트 관리 등 여러 국가 팀이 동일한 워크플로우를 사용하면서도 각자 이해하기 쉬운 언어로 보기를 원할 때 매우 유용합니다.

5. 다국어 리포팅을 위한 커스텀 필드

Odoo Studio나 커스텀 필드로 내부 분류(서비스 카테고리, 리스크 수준 등)를 만들었다면 이 필드를 번역 가능하게 하면 리포트와 대시보드가 사용자 언어에 맞게 보입니다.

이 필드들을 번역하지 않으면 프랑스어 사용자가 리포트에서 영어 라벨을 보게 되어 혼란을 초래하고 시스템 도입률이 낮아질 수 있습니다.

번역 필드 생성 및 커스터마이징 방법

Odoo에서 필드를 번역 가능하게 만드는 방법은 코드 수준과 노코드 환경에서 각각 다릅니다.

파이썬 사용(개발자 권장)

가장 깔끔한 방법은 Python 모델에서 필드를 정의할 때 translate=True를 명시하는 것입니다. 이는 모든 Odoo 기술 문서에서 권장하는 표준 방법입니다:

from odoo import models, fields

class ProductTemplate(models.Model):
    _inherit = 'product.template'

    x_product_highlight = fields.Char(
        string='Product Highlight',
        translate=True
    )

    x_product_note = fields.Html(
        string='Product Note',
        translate=True
    )

이렇게 translate=True만 추가하면 이후의 모든 번역 처리(화면 아이콘, 저장소, 폴백)는 Odoo가 자동으로 관리합니다.

Odoo Studio를 통한 필드

Odoo Studio에서는 필드 설정 패널에 translate 옵션이 기본적으로 보이지 않습니다. Studio에서 만든 Char나 Text 필드는 기본적으로 번역 불가로 생성됩니다.

하지만 생성 후 XML-RPC API를 통해 해당 필드의 translate 속성을 켤 수 있습니다. 먼저 ir.model.fields 에서 필드 ID를 찾고 속성을 업데이트하면 됩니다:

# Find the Studio field
field = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'search_read',
    [[[('name', '=', 'x_my_field'), ('model', '=', 'product.template')]]],
    {'fields': ['id', 'name', 'translate']}
)[0]

# Enable translation
models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'write',
    [[field['id']], {'translate': True}]
)

이 방식은 소스 코드 접근 권한이 없고 스크립트로 맞춤 작업을 하는 팀에 적합합니다.

번역 관리: 내보내기와 가져오기

번역 가능한 필드가 설정되면 Odoo의 번역 워크플로우는 사용하기 쉽습니다:

1. 먼저 설정 > 번역 > 번역 내보내기에서 .po 또는 .csv 파일을 내려받아 해당 언어의 미번역 문자열을 확보합니다.
2. 파일에 번역을 입력하거나 번역가에게 전달합니다.
3. 완성된 파일을 설정 > 번역 > 번역 가져오기로 업로드해 번역을 반영합니다.

제품명 같은 레코드 수준 번역은 필드 옆의 언어 아이콘을 통해 직접 편집할 수도 있어 소량의 콘텐츠 번역에는 편리합니다.

API로 번역 처리하기

XML-RPC API로 번역 가능한 필드를 작성하거나 업데이트할 때는 컨텍스트에 언어를 포함시켜야 합니다:

# Write the French translation for a product name
models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'product.template', 'write',
    [[product_id], {'name': 'Ordinateur Portable Ultra'}],
    {'context': {'lang': 'fr_FR'}}
)

컨텍스트에 특정 언어를 지정해 쓰면 그 언어 값만 업데이트됩니다. 다른 언어의 값은 그대로 유지되므로 외부 시스템에서 번역 콘텐츠를 넣을 때 안전한 방법입니다.

모범 사례

번역 필드를 잘 활용하려면 몇 가지 습관을 들이는 것이 유리합니다.

항상 먼저 기본 언어 값을 설정하세요

다른 언어 번역을 추가하기 전에 기본 언어의 값이 정확하고 완전한지 확인하세요. 다른 번역은 이 값을 기준으로 하며, 기본값을 나중에 변경하면 이미 번역된 값들이 동기화되지 않아 불일치가 발생합니다.

정말 필요한 필드만 번역 대상으로 지정하세요

모든 텍스트 필드를 번역 가능하게 할 필요는 없습니다. 내부 코드, 기술 식별자, 단일 언어로만 사용되는 백오피스 전용 필드는 번역 대상에 포함시키면 관리 부담만 늘어납니다.

대량 번역 작업에는 내보내기/가져오기 워크플로우를 사용하세요

제품 수백·수천 건처럼 큰 카탈로그는 UI에서 하나씩 편집하기 비효율적입니다. 번역 내보내기로 파일을 만들고 일괄 번역 후 가져오는 방식이 훨씬 빠르고 오류도 적습니다.

API 호출 시 항상 언어 컨텍스트를 전달하세요

API로 번역 필드를 읽거나 쓸 때는 반드시 'lang': 'xx_XX'를 컨텍스트에 포함시키세요. 명시하지 않으면 API는 사용자 기본 언어를 사용해 의도치 않게 다른 언어에 데이터를 저장할 수 있습니다.

소스 변경 시 번역 유지 절차를 마련하세요

기본 언어의 값을 바꾸면 다른 언어 번역이 자동 갱신되지 않습니다. 소스 콘텐츠 변경 시 번역가에게 알림이 가도록 검토 프로세스를 만들면 번역 불일치 문제를 예방할 수 있습니다.

자주 발생하는 실수들

경험 많은 Odoo 컨설턴트들도 아래 실수들로 시간을 낭비하곤 합니다. 사전에 숙지하면 디버깅 시간을 크게 줄일 수 있습니다.

API 쓰기에서 언어 컨텍스트를 빠뜨리는 실수

외부 시스템 통합 시 가장 흔한 실수입니다. 언어를 지정하지 않고 제품명을 API로 쓰면 사용자 기본 언어로 값이 덮어써집니다. 예컨대 기본 사용자가 영어로 설정된 경우 원치 않게 영어 값이 변경될 수 있으니 항상 언어를 명시하세요.

검색 시 번역 필드가 필터에 반영된다고 가정하는 오류

번역 필드로 검색하면 활성 언어에서만 검색이 수행됩니다. 영어로 저장된 "Laptop Stand"는 프랑스어 사용자가 프랑스어 번역을 등록하지 않았다면 검색 결과에 나오지 않습니다. 검색 기능이 다국어에서 정상 작동하려면 번역이 갖춰져 있어야 합니다.

리포트에서 번역된 필드와 비번역 필드를 섞어 쓰는 실수

커스텀 리포트나 내보내기에서 번역된 필드와 비번역 필드를 함께 사용하면 출력이 불일치하게 됩니다. 어떤 필드를 번역할지 사전 검토해 통일성을 유지하세요.

계산 필드에서 번역 오버헤드를 간과하는 경우

여러 번역 필드의 값을 합쳐 문자열을 만드는 계산 필드는 요청 시 활성 언어로 계산됩니다. 결과가 언어별로 저장되지 않으므로 다국어로 동일한 계산 결과를 원하면 언어별로 계산을 따로 처리해야 합니다.

언어를 제거하면서 번역 데이터를 정리하지 않는 실수

언어를 비활성화하거나 삭제해도 해당 언어의 번역 값이 데이터베이스에 남을 수 있습니다. 보통 큰 문제는 아니지만 잡동사니가 쌓이니 운영 환경에서 언어를 제거한 뒤에는 번역 데이터를 점검하세요.

요약 및 권장사항

번역 가능한 필드는 다국어 환경에서 매우 실용적인 기능입니다. 단 한 줄의 설정(translate=True)으로 제품 카탈로그, 이메일 템플릿, 웹페이지, 커스텀 필드 등에서 중복 레코드 없이 지역화된 콘텐츠를 유지할 수 있습니다.

핵심은 어떤 필드가 진짜 번역이 필요한지 신중하게 결정하는 것입니다. 사용자 경험에 영향을 주는 곳에만 적용하고, 대량 작업에는 내보내기/가져오기 방식을 사용하며, API 작업 시에는 항상 언어 컨텍스트를 명확히 하세요.

다국어 쇼핑몰 구축, 국제 팀 대상으로 Odoo 배포, 또는 커스텀 모듈 개발 등 어떤 상황이든 번역 가능한 필드를 잘 이해하면 더 깔끔하고 사용자 친화적인 시스템을 만들 수 있습니다.

다국어 Odoo 도입을 진행 중이고 필드 설정이나 번역 워크플로우에 대한 조언이 필요하신가요? Dasolo 팀에 문의하세요 저희가 올바르게 구성할 수 있도록 기꺼이 도와드리겠습니다.