본문으로 건너뛰기
가이드

App 다국어 처리

App의 필드 라벨을 각 언어에 추가하고 PHP와 React에서 사용합니다.

App 다국어 처리

데이터 모델과 마이그레이션의 분류 라벨을 추가합니다. App 루트 기준 다음 파일의 기존 JSON 객체에 항목을 넣으세요.

파일추가 항목
resources/lang/en.json"workshop.note.category.label": "Category"
resources/lang/ko.json"workshop.note.category.label": "분류"
resources/lang/zh.json"workshop.note.category.label": "分类"

기존 항목과 JSON 쉼표를 유지합니다. React에서는 t('workshop.note.category.label'), 요청 처리 중 PHP에서는 __('workshop.note.category.label')로 읽습니다. App 루트에서 JSON 형식·중복 키·문자열 값을 검사합니다.

코드 예시
Shell
nexia check

확인

각 언어로 Note 폼을 다시 열어 라벨과 필드 오류 연결을 확인합니다.

선언에는 번역 키 사용

Navigation·descriptor 등 contribution은 요청 밖에서 발견됩니다. 미리 번역하거나 locale map을 넣지 말고 labelKey, descriptionKey 등 해당 텍스트 역할의 키를 전달하세요. 호스트가 응답을 만들 때 언어를 적용합니다.

Resource 필드는 workshop.note.*, 권한은 permissions.keys.workshop.note.<action>.label과 .description, 메뉴는 App 접두어를 사용합니다. Resource·App의 고정 키는 번역 대상 문구가 아닌 식별자입니다.

공통 화면 문구 재사용

호스트가 렌더링하는 React 화면에서 공통 문구는 앱마다 번역을 복사하지 말고 기존 common.* 키를 사용하세요. 예를 들어 새로고침은 t('common.actions.refresh'), 선택한 법인 중 조회 권한이 있는 법인의 결과만 표시할 때는 t('common.organization_scope.partial_access')를 사용합니다. 부분 결과 안내이므로 전체 결과에는 표시하지 않으며, 이 문구가 접근 권한을 부여하지도 않습니다. 대상 Core 버전에 해당 키가 있어야 합니다. App contribution의 라벨과 앱 고유 업무 문구는 계속 App 카탈로그에 둡니다. 기존 App 키를 제거하기 전에는 프런트엔드·PHP·동적 참조를 모두 확인하세요. 영어 문구가 같다는 이유만으로 의미가 같다고 판단하지 마세요.

다음은 이 버전의 전체 공통 키와 언어별 문구입니다. :count 등은 전달할 값입니다. 예를 들어 React에서 t('common.lookup.selected', { count: 3 })으로 사용합니다. 독립 실행 화면과 PHP에서의 사용 가능 여부는 해당 실행 환경을 확인하세요.

KeyEnglish한국어中文
common.accessibility.requiredRequired필수必填
common.actions.access_request_pendingRequest feature coming soon — contact your administrator directly for now.권한 요청 기능은 준비 중입니다. 지금은 관리자에게 직접 문의해주세요.权限申请功能即将上线 — 当前请直接联系管理员。
common.actions.addAdd추가添加
common.actions.backBack뒤로返回
common.actions.cancelCancel취소取消
common.actions.claimClaim가져오기领取
common.actions.closeClose닫기关闭
common.actions.completeComplete완료完成
common.actions.confirmConfirm확인确认
common.actions.createCreate생성新建
common.actions.deleteDelete삭제删除
common.actions.editEdit편집编辑
common.actions.inviteInvite초대邀请
common.actions.labelActions작업操作
common.actions.moreMore더 보기更多
common.actions.reassignReassign재배정重新分配
common.actions.redoRedo다시 실행重做
common.actions.refreshRefresh새로고침刷新
common.actions.removeRemove제거移除
common.actions.request_accessRequest access관리자에게 권한 요청하기申请访问权限
common.actions.retryRetry재시도重试
common.actions.saveSave저장保存
common.actions.save_draftSave draft임시저장保存草稿
common.actions.searchSearch검색搜索
common.actions.selectSelect선택选择
common.actions.sendSend보내기发送
common.actions.submitSubmit제출提交
common.actions.unassignUnassign배정 해제取消分配
common.actions.undoUndo실행 취소撤销
common.actions.viewView보기查看
common.boolean.falseNo아니요否
common.boolean.trueYes예是
common.cell.emptyNot set없음未设置
common.cell.unavailableUnavailable사용 불가不可用
common.date_picker.calendarCalendar달력日历
common.date_picker.choose_month_yearChoose month and year연도·월 선택选择年月
common.date_picker.clearClear date날짜 지우기清除日期
common.date_picker.next_monthNext month다음 달下个月
common.date_picker.next_yearNext year다음 연도下一年
common.date_picker.open_calendarOpen calendar달력 열기打开日历
common.date_picker.placeholderSelect date날짜 선택选择日期
common.date_picker.previous_monthPrevious month이전 달上个月
common.date_picker.previous_yearPrevious year이전 연도上一年
common.date_picker.todayToday오늘今天
common.date_picker.yearYear연도年份
common.date_range_picker.calendarDate range calendar기간 달력日期范围日历
common.date_range_picker.clearClear date range기간 지우기清除日期范围
common.date_range_picker.open_calendarOpen date range calendar기간 달력 열기打开日期范围日历
common.date_range_picker.placeholderSelect date range기간 선택选择日期范围
common.date_time_picker.dateDate날짜日期
common.date_time_picker.timeTime시간时间
common.dialog.unsaved_changesYou have unsaved changes.저장되지 않은 변경사항이 있습니다.您有未保存的更改。
common.dialog.unsaved_changes_close_hintClosing the tab will discard your changes.탭을 닫으면 변경사항이 사라집니다.关闭标签页将丢失更改。
common.dialog.unsaved_changes_navigation_hintNavigating away will discard your changes.페이지를 이동하면 변경사항이 사라집니다.离开此页面将丢失更改。
common.errors.app_compatibilityThis app is not compatible with the current platform. Ask your administrator to check the app update. Required: :required · Current: :actual.앱과 현재 플랫폼 버전이 호환되지 않습니다. 관리자에게 앱 업데이트 확인을 요청해 주세요. 필요: :required · 현재: :actual.此应用与当前平台不兼容。请联系管理员检查应用更新。要求::required · 当前::actual。
common.errors.app_compatibility_stale_hostThe SDK version this app requires differs from the platform SDK loaded in this browser. The page may predate a platform update: reload it (clear the cache) and, if it persists, ask your administrator to check the app update. Required: :required · Current: :actual.앱이 요구하는 SDK 버전과 이 브라우저에 로드된 플랫폼 SDK 버전이 다릅니다. 플랫폼 업데이트 전에 연 화면일 수 있으니 페이지를 새로고침(캐시 비우기)한 뒤에도 같으면 관리자에게 앱 업데이트 확인을 요청해 주세요. 필요: :required · 현재: :actual.应用要求的 SDK 版本与此浏览器加载的平台 SDK 版本不一致。页面可能在平台更新前打开:请刷新页面(清除缓存),如仍不一致,请联系管理员检查应用更新。要求::required · 当前::actual。
common.errors.app_styles_unsupportedThis app uses styles that the platform cannot display safely. Ask the app developer to check its style compatibility.앱 스타일이 플랫폼과 호환되지 않아 화면을 표시하지 못했습니다. 앱 개발자에게 스타일 호환성 확인을 요청해 주세요.此应用的样式与平台不兼容,无法显示。请联系应用开发者检查样式兼容性。
common.errors.app_unavailableThis app is unavailable. Check its installation and your access, then retry.앱을 열 수 없습니다. 설치 상태와 접근 권한을 확인한 뒤 다시 시도해 주세요.无法打开此应用。请检查安装状态和访问权限,然后重试。
common.errors.browser_style_unsupportedYour browser does not support this app’s isolated styles. Update your browser and try again.브라우저가 앱 스타일 격리를 지원하지 않습니다. 브라우저를 업데이트한 뒤 다시 시도해 주세요.浏览器不支持应用样式隔离。请更新浏览器后重试。
common.errors.forbiddenYou no longer have permission to complete this action.이 작업을 완료할 권한이 더 이상 없습니다.您已无权完成此操作。
common.errors.networkCould not reach the server. Check your connection and try again.서버에 연결할 수 없습니다. 네트워크 연결을 확인한 뒤 다시 시도하세요.无法连接服务器。请检查网络连接后重试。
common.errors.serverThe server could not complete this action. Your input is still here; try again shortly.서버가 작업을 완료하지 못했습니다. 입력 내용은 유지되므로 잠시 후 다시 시도하세요.服务器无法完成此操作。您的输入仍会保留,请稍后重试。
common.errors.unauthenticatedYour session has expired. Sign in again, then retry.로그인이 만료되었습니다. 다시 로그인한 뒤 재시도해 주세요.登录已过期。请重新登录后重试。
common.fields.created_atCreated생성일시创建时间
common.fields.legal_entityLegal Entity법인法人实体
common.fields.updated_atUpdated수정일시更新时间
common.filters.all_legal_entitiesAll authorized Legal Entities조회 가능한 모든 법인所有有权查看的法人实体
common.filters.all_operating_unitsAll authorized Operating Units조회 가능한 모든 운영 조직所有有权查看的运营单元
common.filters.legal_entityLegal Entity법인法人实体
common.filters.operating_unitOperating Unit운영 조직运营单元
common.filters.selected_count:count selected:count개 선택已选择 :count 项
common.lookup.all_failedCould not load all results. Your selection is unchanged. Try again.전체 결과를 불러오지 못했습니다. 기존 선택은 유지됩니다. 다시 시도해 주세요.无法加载全部结果。已保留原有选择,请重试。
common.lookup.all_limitSelect up to :count items. Narrow your search or filters to select all results.최대 :count개까지 선택할 수 있습니다. 검색이나 필터로 범위를 좁힌 후 전체 선택해 주세요.最多可选择 :count 项。请缩小搜索或筛选范围后再全选。
common.lookup.applyApply적용应用
common.lookup.clearClear selection선택 초기화清除选择
common.lookup.detailsDetails상세 정보详细信息
common.lookup.emptyNo matching items.조건에 맞는 항목이 없습니다.没有匹配的项目。
common.lookup.filtersMore filters상세 필터更多筛选
common.lookup.limitSelect up to :count items.최대 :count개까지 선택할 수 있습니다.最多可选择 :count 项。
common.lookup.loadingLoading…불러오는 중…正在加载…
common.lookup.nextNext다음下一页
common.lookup.page_selectionThe header checkbox selects the current page.표 머리글의 체크박스는 현재 페이지를 선택합니다.表头复选框仅选择当前页。
common.lookup.previousPrevious이전上一页
common.lookup.resultsResults: :count검색 결과 :count개搜索结果::count 项
common.lookup.retryRetry다시 시도重试
common.lookup.searchSearch검색搜索
common.lookup.select_all_resultsSelect all :count results검색 결과 :count개 전체 선택选择全部 :count 条结果
common.lookup.select_pageSelect this page현재 페이지 선택选择当前页
common.lookup.selectedSelected :count선택 :count개已选择 :count 项
common.lookup.selected_onlySelected items선택한 항목已选项目
common.organization_scope.invalidThe organization scope in this link is invalid.이 링크의 조직 범위가 올바르지 않습니다.此链接中的组织范围无效。
common.organization_scope.loadingLoading organization scope…조직 범위를 불러오는 중…正在加载组织范围…
common.organization_scope.partial_accessOnly data from selected legal entities you can access is shown.선택한 법인 중 조회 권한이 있는 법인의 데이터만 표시합니다.仅显示所选法人中您有权访问的法人的数据。
common.organization_scope.record_scopeRecord scope자료 범위记录范围
common.organization_scope.records_allAll전체全部
common.organization_scope.records_legal_entityLegal entities법인 전용法人专用
common.organization_scope.records_tenantCompany-wide기업 공통企业通用
common.organization_scope.unavailableNo organization scope is available.사용 가능한 조직 범위가 없습니다.没有可用的组织范围。
common.pagination.labelPagination페이지 이동分页
common.pagination.nextNext다음下一页
common.pagination.previousPrevious이전上一页
common.pagination.status:current of :total:current / :total:current / :total
common.requirements.missing:count readiness fields are still empty사용 준비 항목 :count개가 비어 있습니다仍有 :count 个就绪字段未填写
common.requirements.readiness_completeReady to use사용 준비 완료已可使用
common.requirements.readiness_progressReady :complete/:total사용 준비 :complete/:total使用准备 :complete/:total
common.requirements.readiness_requiredNeeded before use사용 시작에 필요使用前需要
common.requirements.save_requiredNeeded to save저장에 필요保存时需要
common.status.emptyNo records yet.등록된 항목이 없습니다.暂无记录。
common.status.empty_descriptionCreate the first record to start using this list.첫 레코드를 등록하여 이 목록을 사용해 보세요.创建第一条记录以开始使用此列表。
common.status.errorAn error occurred.오류가 발생했습니다.发生错误。
common.status.error_descriptionSomething went wrong while loading this. Try again in a moment.불러오는 중 문제가 발생했습니다. 잠시 후 다시 시도해 주세요.加载时出现问题,请稍后重试。
common.status.loadingLoading...로딩 중...加载中...
common.status.manage_deniedYou do not have permission to manage :subject.:subject 관리 권한이 없습니다.您没有管理:subject的权限。
common.status.no_accessYou do not have access to this resource.이 항목에 접근할 수 있는 권한이 없습니다.您没有访问此资源的权限。
common.status.no_access_descriptionPlease contact your administrator to request the required permission.이 항목을 열람하려면 관리자에게 권한을 요청해 주세요.请联系管理员申请所需的权限。
common.status.no_resultsNo results found.검색 결과가 없습니다.没有找到结果。
common.status.no_results_descriptionTry a different search term or clear filters to broaden the results.다른 검색어를 입력하거나 필터를 해제하여 더 많은 결과를 확인하세요.请尝试其他搜索词或清除筛选条件以查看更多结果。
common.status.not_foundThe requested item could not be found.요청하신 항목을 찾을 수 없습니다.未找到所请求的项目。
common.status.not_found_descriptionThe item may have been deleted or moved to a different location.해당 항목이 삭제되었거나 다른 위치로 이동되었을 수 있습니다.该项目可能已被删除或移至其他位置。
common.status.savingSaving...저장 중...保存中...
common.tooltip.more_informationMore information추가 정보更多信息
common.validation.boolean:field must be true or false.:field은(는) 참 또는 거짓 값이어야 합니다.:field必须为真或假。
common.validation.choiceSelect a valid :field.올바른 :field을(를) 선택해 주세요.请选择有效的:field。
common.validation.code_formatUse letters, numbers, underscores (_), and hyphens (-).영문, 숫자, 밑줄(_), 하이픈(-)만 사용할 수 있습니다.只能使用字母、数字、下划线(_)和连字符(-)。
common.validation.integer:field must be an integer.:field은(는) 정수로 입력해 주세요.:field必须为整数。
common.validation.invalid:field is invalid.:field 값이 올바르지 않습니다.:field无效。
common.validation.max_number:field must be :max or less.:field은(는) :max 이하이어야 합니다.:field必须不超过:max。
common.validation.max_string:field must be :max characters or fewer.:field은(는) :max자 이하로 입력해 주세요.:field必须不超过:max个字符。
common.validation.min_number:field must be at least :min.:field은(는) :min 이상이어야 합니다.:field必须至少为:min。
common.validation.numeric:field must be a number.:field은(는) 숫자로 입력해 주세요.:field必须为数字。
common.validation.required:field is required.:field을(를) 입력해 주세요.请输入:field。
common.validation.string:field must be text.:field은(는) 텍스트로 입력해 주세요.:field必须为文本。
common.validation.summaryPlease review the highlighted fields.표시된 입력값을 확인해 주세요.请检查高亮显示的字段。
common.validation.unique:field is already in use.이미 사용 중인 :field입니다.:field已被使用。
common.work_labels.edit_record:record Edit:record 편집编辑:record
common.work_labels.edit_resourceEdit :resource:resource 편집编辑:resource
common.work_labels.new_resourceNew :resource새 :resource新建:resource

다음 키는 Core 서버 전용입니다. 앱 React 화면으로 제공되지 않으며, 앱 PHP에서도 호스트 키가 제공된다고 가정하지 마세요.

KeyEnglish한국어中文
common.validation.image_sourceEnter an https:// URL or a path that starts with / .https:// 주소 또는 /로 시작하는 경로를 입력해 주세요.请输入 https:// 地址或以 / 开头的路径。
common.validation.select_one_authorized_legal_entitySelect one authorized Legal Entity.권한이 있는 법인 하나를 선택해 주세요.请选择一个已获授权的法人实体。
common.validation.the_phone_number_must_be_a_valid_phone_numberThe phone number must be a valid phone number.전화번호는 유효한 전화번호여야 합니다.电话号码必须是有效的电话号码。
common.validation.work_context_unavailableThe selected work context is unavailable.선택한 업무 컨텍스트를 사용할 수 없습니다.所选工作上下文不可用。

Catalog는 값이 모두 문자열인 평면 JSON 객체입니다. 키에는 점이 필요하고 콜론은 쓰지 않습니다. 소유 경로 조각은 lowercase snake_case를 사용하며 고정 kebab-case 식별자와 enum의 정확한 토큰은 허용합니다. 언어별 placeholder를 맞추고 자연스러운 문구를 작성하세요. 생성기는 기존 catalog에 병합합니다. 중국어 fallback으로 생성된 문구도 릴리스 전에 검토해야 합니다.

상태와 검증 연결 재사용

기본 Note에는 상태 필드나 NoteStatus enum이 없습니다. 상태를 직접 추가한다면 저장값과 라벨 키의 소유자를 앱 안에 정하고, 필터 선택지·descriptor·화면이 같은 정의를 사용하게 하세요. 보호된 API 추가하기는 문자열 상태로 보관 동작을 추가하는 예제입니다. enum을 도입하는 경우 cast와 번역도 함께 연결합니다.

생성 폼은 서버 필드명을 Resource 라벨 키에 연결하고 SDK schema로 오류를 전달합니다. workshop.note.category.label을 추가하면 되며 별도 오류 라벨을 하드코딩하지 않습니다.

nexia check는 파일 형식을 확인합니다. 언어 간 placeholder 일치, 실제 화면의 라벨 누락·품질은 별도로 검증하세요. Descriptor 라벨은 Resource 계약, 폼의 텍스트 역할은 React 컴포넌트와 훅을 참고합니다.

길이 제한과 실행 준비 검증

설명문을 포함한 각 번역 값은 유니코드 문자 2,000자까지 허용합니다. 내보낸 런타임 카탈로그 전체는 1MiB, 로케일은 20개, 로케일별 내보낸 키는 1,000개까지입니다. DB 컬럼 크기가 아니라 플랫폼 검증 규칙입니다. 로컬 nexia check는 모든 번역 값의 길이를 확인하고, 서버는 내보낸 번역과 전체 카탈로그를 검증합니다.

대응하는 Core·sandbox-manager·SDK/devtools·CLI 버전을 함께 적용하면 개발 실행 준비 중 migration·초기화·백엔드 시작 전에 카탈로그를 검증합니다. CATALOG_VALIDATION_FAILED는 잘못된 필드를 제한된 개수로 표시하며, 번역 길이 오류에는 resources/lang/<locale>.json, 정확한 키, 허용 길이와 실제 길이가 나옵니다. 소스를 수정하고 nexia check를 실행한 뒤 해당 작업의 재시도 안내를 따르세요. 데이터 실행 전 검증만 실패한 작업은 종료 확인 후 재시도할 수 있지만, 과거 needs_review 작업은 여전히 운영자 확인이 필요합니다. DB 초기화나 .nexia 삭제는 필요하지 않습니다.

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

원본 위치: docs/developers/content/ko/building-apps/localize-an-app.md