모범 사례

웹용

예시: 앵커가 있는 <h2/> 태그의 경우

현재 언어의 레이블

LLM은 링크 보호에 있어 사람보다 더 효율적이며, LSDE는 다양한 언어 버전 간의 문제를 감지할 수 있도록 합니다.
따라서 모든 언어에서 작동하는 링크를 공유하고 LSDE를 사용하여 더 이상 사용되지 않는 앵커의 교체를 관리할 수 있습니다.

코드의 모호성

데이터 지향 모델로 작업할 때는 모호함을 피하십시오.
예시:
나쁜 사례: 'key'라는 용어는 명확하지 않아 검색을 어렵게 만듭니다.

ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		key: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		key: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		key: 'software:lsge.name',
	},
];

좋은 사례: 단일하고 일관된 규칙을 채택하십시오.
'i18nKey'라는 용어는 매우 명확하며 정규 표현식('Regex')을 통해 이 값을 정확하게 검색할 수 있습니다.

ts
const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		i18nKey: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: '<c1>LSDE</c1>',
		i18nKey: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		i18nKey: 'software:lsge.name',
	},
];

게으름

나쁜 아이디어는 게으름에서 비롯됩니다.

콘텐츠를 검색하기 위해 연산을 수행하여 키를 절약하려고 하지 마십시오.
예시:

javascript
const [title, subtitle] = t( 'game:game.title' ).split( /[:：]/ );

이는 잘못된 좋은 생각입니다. 왜냐하면 일부 언어에서는 문자가 다를 수 있고 단어 순서가 변경될 수 있기 때문입니다.

태그 형식

텍스트에 직접 디자인 관련 코드를 최소화하여 코드베이스에서 제어하십시오.
예를 들어, 이미지의 위치는 지정할 수 있지만, 스타일이나 렌더링 방식은 지정할 수 없습니다.
디자인 변경이 필요할 때, 단지 태그의 스타일을 변경하기 위해 10개 언어로 된 텍스트를 다시 번역해야 하는 제약을 받고 싶지 않을 것입니다!

태그는 식별자를 포함할 수 있지만, 추가 정보를 추가하는 것은 일반적으로 강력히 권장되지 않으며 나쁜 사례입니다.
예시: <img src='url' left />처럼 하지 마십시오. 대신 <img id=1 />를 사용하십시오.
그런 다음 이미지 태그의 ID를 가져와 코드베이스에서 필요한 스타일을 적용할 수 있습니다.
ID는 인덱스를 통하는 대신 리터럴하게 사용되어야 합니다.
실제로 다른 언어에서는 태그가 이동되어 초기 인덱스와 더 이상 일치하지 않을 수 있습니다.
자연스러운 인덱스를 사용하는 것은 개발자에게도 복잡성을 초래합니다. 이미지나 태그가 어떤 인덱스에 해당하는지 추측하는 것은 정말 골치 아픈 일입니다.
따라서 보간 후 사용자 정의할 수 있도록 식별자가 있는 태그를 사용하십시오.

CSS

사이트 번역 시, 단락이 있는 경우 언어 변경 시 시각적 이동을 방지하기 위해 번역 후 최소 높이(`min-height`)를 선택하십시오.
예시: `mih={'3lh'}`
이는 가장 많은 줄을 차지하는 언어를 기반으로 최소 높이를 정의할 수 있게 하여, 일관되고 깔끔한 사용자 경험(UX)을 보장합니다.

네임스페이스

이는 키를 찾는 정규 표현식(Regex) 패턴을 설정하는 데 큰 도움이 됩니다.
예시: game:a.b.c, common:a.b.c

GIT 버전 관리

.lsde 프로젝트는 JSON 포맷의 파일이므로 Git과 같은 도구를 사용하여 버전을 관리하기 용이합니다.
완벽한 히스토리 기록과 보안 강화를 위해 프로젝트를 Git 리포지토리에 저장하는 것을 강력히 권장합니다.
LSDE 자체 백업 시스템이 내장되어 있지만, 데이터 파일 관리를 위한 최적의 솔루션은 여전히 Git입니다.

컨텍스트 및 작성

명시적인 컨텍스트는 키의 이름, 경로(계층 구조), 주변 요소(부모/자식 키) 또는 메타데이터에 포함될 수 있습니다.
추측의 여지가 있는 모호한 키를 피하십시오. 키를 읽을 때 코드에서 그 용도를 확인해야 한다면, 데이터 아키텍처를 개선해야 한다는 신호입니다.

명시적인 키의 예시:
game:.scenes.001.events.001.1
game:.scenes.001.events.001.2
game:.scenes.the-ice-land.events.the-lost-house.1
game:.scenes.the-ice-land.events.the-lost-house.2
game:.ui.menus.new-game.label
game:.ui.menus.new-game.description

이러한 키들은 대화나 인터페이스 요소를 가리키고 있음을 즉시 이해할 수 있게 해줍니다.

나쁜 사례 예시:
game:events.001.1 (너무 모호함: 이 이벤트가 어디에서 사용되는가?)
game:.scenes-events-the-lost-house.1 (경로의 중복)
game:.ui-menus.new-game-label (불필요한 결합)

경로에서 중복을 피하십시오. 검색을 쉽게 만들어야 한다면, JSON 데이터 구조를 훼손하는 대신 연결된 키들을 포함하는 타입(types) 파일을 내보내십시오.

문자열은 이해를 돕기 위해 외부 요소(화면 위치, 색상, 아이콘)에 의존해서는 안 됩니다.
예: 다음을 피하십시오.
"여기를 클릭하여 계속하기"
다음과 같이 작성하십시오.
"결제로 이동"
텍스트는 UI(사용자 인터페이스)에서 분리되어 추출된 상태에서도 이해할 수 있어야 합니다.
일부 언어는 번역이 불가능하거나 액션과 텍스트 위치에 따라 문구 구성이 달라질 수 있습니다.

액션 텍스트는 액션과 대상을 설명해야 합니다: 상세한 설명 없이 "여기를 클릭" 또는 "더 보기"라고 하는 대신 "결제하러 가기", "PDF 보고서 다운로드"와 같이 작성하십시오.

S.O.L.I.D.와 같은 프로그래밍 원칙을 i18n 콘텐츠 작성에 그대로 적용하지 마십시오. 작성과 코드는 서로 다른 분야입니다.
언어마다 고유한 구문(syntax)이 있으므로, 파편화된 조각보다는 완전한 문장을 선호하십시오.
`i18next`와 같은 프레임워크가 중첩(nesting)을 지원하지만, 이는 종종 불필요한 복잡성을 야기합니다. 변화가 필요하다면 문장 전체를 다시 작성하십시오. 보간(interpolation)은 이름이나 숫자와 같은 단순한 변수로 제한하십시오.

인터페이스에 글자 수 제한이나 길이 제약이 있는 경우, 메타데이터에 이를 명시하고 시각 자료(스크린샷 또는 목업)를 제공하십시오.
프로그래머가 전 세계 모든 언어에 맞춰 UI를 동적으로 만드는 것보다 번역가가 제한적인 인터페이스에 맞춰 텍스트를 조정하는 것이 훨씬 간단합니다. 이를 작성자에게 위임하는 것이 더 나은 사용자 경험(UX)을 보장합니다.

텍스트에 특수 문자나 이모지를 직접 삽입하지 마십시오.
코드를 통해 렌더링을 제어할 수 있도록 변수(예: <t title=)를 사용하십시오. 이모지의 렌더링은 사용자의 운영 체제와 환경에 따라 크게 달라집니다.

관용구, 언어유희, 지역적 은유는 범용적인 문자열에서 지양해야 합니다.
한 언어에서는 명확한 표현이 다른 언어에서는 황당하거나 번역 불가능할 수 있습니다.

번역가가 코드나 UI에 접근할 수 없는 것처럼 작성하십시오.
이해에 필요한 모든 정보는 키, 계층 구조 또는 메타데이터에 포함되어야 합니다.

I18n 기술

위치 인덱스(`{0}`, `{1}`)보다 명명된 Placeholder(`{username}`, `{count}`)를 우선적으로 사용하세요. LSDE는 변수의 컨텍스트를 정의하고 프로젝트 내에서 추적 가능성을 보장하기 위해 변수 전용 섹션을 제공합니다.

각 Placeholder는 원자적이어야 하며 고유한 데이터(이름, 날짜, 숫자)를 나타내야 합니다. 번역과 해석을 어렵게 만드는 범용적이거나 다형적인 변수는 피하십시오.

오른쪽에서 왼쪽으로 쓰는 언어의 표시 방식을 미리 고려하십시오. 문자열을 수동으로 수정하지 않고도 렌더링이 유연하고 구조적으로 올바르게 유지되어야 합니다.

여러 번역 키를 결합하여 문장을 구성하지 마십시오. 각 언어 고유의 구문과 문법적 일치를 준수하기 위해, 모든 전체 문장은 하나의 고유 키에 대응해야 합니다.