추적

Lunaria는 Git을 기반으로 하는 독특한 지역화 추적 시스템을 구현합니다. 이 가이드에서는 시스템의 작동 방식, 조작 방법, 그리고 관련된 모든 기능을 설명합니다.

작동 방식

변경 사항을 추적하기 위해, Lunaria는 소스 파일과 로컬라이제이션 버전의 최신 메이저 커밋 날짜를 비교하여 사용합니다. 만약 로컬라이제이션 파일이 소스 파일보다 최근에 수정되었으면, 그 상태는 최신으로 간주됩니다. 그렇지 않으면 오래되었으므로 과거 상태로 간주됩니다.

“메이저 커밋”은 내용 변경이 중요한 커밋을 의미합니다. 메이저 커밋이 추적 대상 브랜치에 병합되면, 이를 통해 Lunaria의 상태가 변경됩니다. 이러한 상태 변화는 예측 가능하며, 다음 중 하나만 가능합니다:

소스 콘텐츠가 변경되어, 로컬라이제이션은 오래되었음을 표시함.
로컬라이제이션이 업데이트되어, 완료됨을 표시함.

기본적으로 모든 커밋은 _메이저_로 간주되며, 일부 커밋을 메이저로 간주하지 않도록 하려면, Lunaria는 상태 변경 조작 방법을 몇 가지 제공합니다.

추적 시스템 설정

Lunaria의 추적 시스템에 파일을 추가하려면 lunaria.config.json 파일에 files 필드를 추가해야 합니다. 이 필드는 파일 유형의 객체 배열을 받으며, 아래 예시와 같습니다:

{
  "files": [
    {
      "location": "src/content/docs/**/*.md",
      "pattern": "src/content/docs/@lang/@path",
      "type": "universal"
    }
  ]
}

이 예시에서, Lunaria는 src/content/docs 디렉터리 및 하위 디렉터리 내의 모든 마크다운 파일을 추적합니다. files 배열에 더 많은 항목을 추가하면, 다른 파일 집합을 다르게 추적하거나 생성된 대시보드에서 보다 잘 정렬할 수 있습니다. 배열 순서는 유지됩니다.

이 모든 필드의 작동 방식을 더 깊이 이해하기 위해 아래 내용을 읽어보세요.

`location`

location 필드는 추적할 모든 로케일 내의 원하는 파일을 일치시키기 위한 글로브 패턴 문자열을 기대합니다.

Lunaria의 글로브 패턴은 micromatch를 기반으로 하며, 이 문서에서 글로브 패턴을 설명하는 것은 적절하지 않지만, 다음은 유용하게 사용할 수 있는 몇 가지 일반적인 스크립트입니다:

**/*.md: 디렉터리 및 하위 디렉터리 내의 모든 .md 파일을 매칭.
*.md: 디렉터리 내의 모든 .md 파일을 매칭.
**/*.{md,mdx}: 디렉터리 및 하위 디렉터리 내의 모든 .md 및 .mdx 파일을 매칭.
**/!(index).md: 디렉터리 및 하위 디렉터리 내의 모든 .md 파일을 매칭, 단 index.md 파일은 제외.

`pattern`

pattern 필드는 path-to-regexp 문자열을 기대하며, 파일들의 공통 경로를 추출하고 관계를 유추하는 데 사용됩니다. Lunaria는 @lang와 @path 자리 표시자를 제공하여, 로케일과 경로의 나머지 부분을 어디에 삽입할지를 표시하도록 도와줍니다.

매우 드문 경우에, @lang와 @path는 프로젝트의 파일 구조를 올바르게 표현하지 못할 수 있습니다. 내부적으로 이 자리 표시자는 약간의 견해가 강한 :lang와 :path 경로 파라미터로 바뀝니다. 또한 이 파라미터를 자리 표시자 대신 사용할 수 있으며, 접두사, 접미사 및/또는 수정자를 조정하여 프로젝트의 파일 구조에 맞게 설정할 수 있습니다.

예를 들어, 매우 고유한 국제화 파일 구조를 지원하는 Nextra의 경우, @path 대신 :path+를 사용한 다음 패턴을 다음과 같이 사용할 수 있습니다:

{
  "files": [
    {
      "location": "pages/**/*.mdx",
      "pattern": "pages/:[email protected]",
      "type": "universal"
    }
  ]
}

`type`

type 필드는 이 파일들이 Lunaria에서 어떻게 처리될지를 결정합니다. 다양한 유형은 대시보드에서 파일이 어떻게 표시되는지 변경하거나 확장하며, 각각 다른 요구사항(예: 지원되는 파일 형식), 그리고 과거/완료 상태 계산 방식이 다릅니다.

자세한 정보는 구성 참조의 파일 유형 섹션을 참고하세요.

`ignore`

선택적으로 ignore 필드를 추가하여 특정 파일을 추적에서 제외할 수 있습니다. 이 필드는 무시할 파일을 매칭하기 위한 글로브 패턴 문자열 배열을 기대합니다. 예를 들어:

{
  "files": [
    {
      "location": "src/content/docs/**/*.md",
      "pattern": "src/content/docs/@lang/@path",
      "type": "universal",
      "ignore": ["src/content/docs/**/old.md"]
    }
  ]
}

지역화를 위한 파일 세부 설정

특정 파일만 지역화를 허용하고 싶을 수도 있습니다. 예를 들어, 소스 로케일에서 일주일 이상 지나지 않은 파일, 또는 곧 재구조화될 예정인 파일 등을 제외하는 것입니다.

이 작업을 수행하는 한 가지 방법은 ignore 필드를 사용해 특정 파일을 제외하는 것이지만, 이 경우 파일이 지역화 가능한 상태가 되었을 때마다 구성 파일을 수동으로 업데이트해야 합니다.

반면, 앞말 메타데이터(예: 마크다운, MDX, YAML)를 수락하는 파일에 사용 가능한 localizableProperty를 사용할 수 있습니다. 이 속성이 true인 모든 파일은 대시보드에 추가되고, 그렇지 않은 파일은 제외됩니다:

lunaria.config.json 파일에 localizableProperty 필드를 추가하고, 지역화를 활성화하는 데 사용할 앞말 속성 이름을 지정합니다:
lunaria.config.json
```
{
  "localizableProperty": "isLocalizable"
}
```
지역화를 활성화하려는 파일에 값이 true인 앞말 속성을 추가합니다:
my-page.mdx
```
---
title: My page
isLocalizable: true
---

# My MDX page
```

상태 변경 조작

몇몇 경우에, 원하지 않는 상태 변경이 발생하는 것을 막기 위해 추적 시스템에 개입하는 것이 중요할 수 있습니다.

예를 들어, 소스 콘텐츠의 오타 수정과 같은 변경 사항은 로컬라이제이션을 오래된 것으로 표시해서는 안 되며, 혹은 과거 상태인 로컬라이제이션 내에서 깨진 링크를 업데이트하는 변경 사항은 완료 상태로 표시해서는 안 됩니다.

커밋 무시

커밋 내의 모든 변경 사항을 무시하려면, 커밋 또는 머지 요청의 제목에 ignoreKeyword를 추가할 수 있습니다(병합 시 스쿼시 모드 사용 시). 기본적으로 fix typo와 lunaria-ignore라는 키워드는 무시됩니다.

예를 들어, 다음 커밋 제목은 무시됩니다:

[lunaria-ignore] Format localization files

반면, 다음 커밋 제목은 상태 변경을 트리거합니다:

Add a new section on `getting-started.mdx` file

다른 ignoreKeywords를 추가할 수 있으며, 기본값을 덮어쓸 수 있습니다:

lunaria.config.json 파일에 ignoreKeywords 필드를 추가하고, 무시할 키워드 배열을 지정합니다:
lunaria.config.json
```
{
  "ignoreKeywords": ["@ignore", "[ci]", "[format]"]
}
```

ignoreKeywords 기능은 완전히 비활성화할 수도 있습니다:

lunaria.config.json 파일에 ignoreKeywords 필드를 추가하고, 빈 배열을 지정합니다:
lunaria.config.json
```
{
  "ignoreKeywords": []
}
```

파일별로 상태 변경 트리거

때때로 커밋에는 상태 변경을 트리거해야 할 변경 사항과 그렇지 않은 변경 사항이 모두 포함될 수 있습니다. 특히 파일 간 순환 참조가 존재하여 에러를 피하기 위해 동일한 머지 요청 내에 있어야 할 경우에 해당됩니다. 이럴 경우, 최선의 선택은 트래커 지시문을 사용하는 것입니다.

트래커 지시문은 커밋 설명에 추가되는 사용자 지정 문법으로, ;로 분리된 파일 또는 글로브 목록을 포함하며, 트래커 지시문에 의해 고려됩니다:

@lunaria-ignore:docs/en/first.mdx;docs/ja/second.mdx;docs/**/third.mdx

`@lunaria-track`

@lunaria-track 지시문은 나열된 모든 파일의 변경 사항을 추적하고, 같은 커밋에 포함되지 않은 모든 파일은 무시합니다.

예시:

@lunaria-track:src/content/docs/en/**.mdx

`@lunaria-ignore`

@lunaria-ignore 지시문은 나열된 모든 파일의 변경 사항을 무시하고, 같은 커밋에 포함되지 않은 모든 파일은 추적합니다.

예시:

@lunaria-ignore:src/content/docs/ja/**.mdx