국제화 (Internationalization)

앱에 다국어 지원을 추가하세요. 편집 콘텐츠 현지화에는 Proyecta Content API를 활용하거나, AI에게 코드에서 직접 i18n 프레임워크를 연결해 달라고 요청하세요.

Proyecta는 앱을 국제화하는 두 가지 보완적인 방법을 지원합니다.

Proyecta Content API를 통한 콘텐츠 현지화 — 여러 언어로 번역이 필요한 편집 콘텐츠(블로그 글, FAQ, 마케팅 문구 등)에 적합
번역 프레임워크를 통한 코드 레벨 i18n — UI 문자열, 날짜, 통화, 런타임 로케일 전환에 적합

두 방법 모두 지금 바로 사용할 수 있습니다. 어떤 방법이 필요한지는 무엇을 번역하느냐에 따라 다릅니다.

빌더인 Proyecta 자체는 24개 로케일을 지원하므로, 제품 자체가 i18n에 능숙합니다. 이 안에서 만드는 앱에도 동일한 패턴을 적용할 수 있습니다.

옵션 1: 콘텐츠 현지화 (Proyecta Content API)

블로그, 지식 베이스, 마케팅 페이지, 상품 카탈로그 등 콘텐츠 중심 사이트를 만들고 있다면, 내장 로케일 지원을 활용하세요. 지원할 언어를 AI에게 알려 주면("Make the site available in English, Spanish and French") 영어를 기본값으로 하여 대신 등록해 줍니다. 그런 다음 방문자의 언어로 콘텐츠를 가져오면 됩니다.

프론트엔드에서는 템플릿의 타입이 지정된 콘텐츠 훅이 현지화된 필드를 자동으로 처리합니다. 방문자의 활성 로케일을 전달하면 각 localized 필드가 단일 번역 값으로 반환됩니다.

import { useCollection, useEntry } from '@/hooks/useContent';
import { useTranslation } from 'react-i18next';

function Blog({ slug }: { slug: string }) {
    const { i18n } = useTranslation();

    // List a collection in the current locale
    const { data: posts } = useCollection('posts', { locale: i18n.language });

    // Or read one entry by slug in the current locale
    const { data: post } = useEntry('posts', slug, { locale: i18n.language });

    // ...render posts / post
}

내부적으로 CMS는 폴백 체인을 따릅니다. 요청한 로케일 → 설정된 폴백 → 기본 로케일 순으로 탐색하며, 실제로 반환된 로케일 코드를 각 엔트리의 localeResolved로 보고합니다. 단일 언어 사이트에서 locale을 생략하면 필드가 원시 값으로 반환됩니다.

다음 경우에 이 방법이 적합합니다:

코드를 작성하지 않는 편집자가 콘텐츠를 번역해야 할 때
번역 내용을 버전 관리하고 싶을 때
로케일별 게시가 필요할 때 (예약 게시는 곧 지원 예정 — 현재 엔트리는 API를 통한 수동 게시가 필요합니다)

전체 Content API는 콘텐츠 관리를 참고하세요.

옵션 2: 코드 레벨 i18n 프레임워크

레이블, 버튼, 오류 메시지, 날짜, 통화 등 UI 문자열에는 AI에게 i18n 프레임워크를 프로젝트에 직접 연결해 달라고 요청하세요.

Add internationalization to my app.
Support English, Spanish, French, and Arabic.
Add message catalogs in src/locales/.
Add a language switcher in the header.
Use locale-prefixed URLs like /en/about and /es/about.
Make sure RTL layout works correctly for Arabic.

AI는 다음 작업을 수행합니다:

프레임워크 선택 — Proyecta의 표준인 react-i18next와 함께 i18next를 사용합니다.
카탈로그 파일 생성 — src/locales/에 언어별 JSON 파일을 만듭니다.
텍스트 래핑 — react-i18next의 useTranslation 훅에서 가져온 t() 호출로 텍스트를 감쌉니다.
언어 전환기 컴포넌트 추가
로케일 접두사를 포함한 URL 라우팅 연결
RTL 레이아웃 처리 — 아랍어, 히브리어 등에 dir="rtl" 적용
로케일에 맞는 숫자, 날짜, 통화 포맷팅

AI로 자동 번역하기

기본 언어가 준비되면, AI를 활용해 나머지 카탈로그 파일을 빠르게 만들 수 있습니다.

"src/locales/en.json의 모든 문자열을 스페인어, 프랑스어, 독일어, 일본어로 번역해줘. 자연스럽고 관용적인 표현을 사용하고, 브랜드명은 번역하지 마."
"앱 전체가 영어로 만들어져 있어. 모든 내용에 스페인어 번역을 추가하고 es/ 경로 접두사도 붙여줘."

법률 문구, 의료, 금융 등 중요도가 높은 콘텐츠는 출시 전에 전문 번역가가 AI 번역 결과를 검토하도록 하세요.

두 방법 함께 사용하기

실제 앱 대부분은 두 방법을 모두 활용합니다. 버튼, 오류 메시지, 내비게이션 등 UI 요소에는 코드 레벨 i18n을, 아티클이나 상품 설명 등 편집 콘텐츠에는 Content API를 사용하는 방식입니다. 두 방법은 깔끔하게 공존합니다. i18n 프레임워크는 빌드 타임에 카탈로그 파일을 처리하고, Content API는 런타임에 현지화된 엔트리를 제공합니다.

모범 사례

기본 언어를 정하고 문구를 먼저 확정하세요. 계속 바뀌는 내용을 번역하는 것은 매우 번거롭습니다.
번역은 일괄 처리하세요. 진행하면서 번역하지 말고, 기능이 안정될 때까지 기다리세요.
아랍어나 히브리어를 지원한다면 RTL을 초기에 테스트하세요. RTL 버그는 직접 확인하기 전까지 눈에 띄지 않습니다.
<html>에 lang과 dir을 포함하세요. 브라우저와 스크린 리더가 이 값에 의존합니다.
포맷팅에는 Intl을 사용하세요. 날짜나 통화 포맷팅을 직접 구현하지 말고 Intl.DateTimeFormat, Intl.NumberFormat을 활용하세요.

곧 출시 예정

빌더 내 로케일 관리 UI — Proyecta를 벗어나지 않고 로케일 선택, 번역 현황 확인, 카탈로그 편집 가능
새 문자열 저장 시 자동 번역
프레임워크가 미리 연결된 i18n 지원 프로젝트 템플릿