This page is a translated version of the page Web2Cit/Docs/Storage and the translation is 100% complete.

The Web2Cit storage is the part of the Web2Cit ecosystem responsible for keeping the collaboratively defined configuration files that dictate the behavior of Web2Cit.

As will be explained in the following sections, these configuration files are JSON files saved as wiki pages on Meta-Wiki.

They are defined collaboratively, with the help of Web2Cit editing tools, on a per-domain basis, with up to three configuration files per domain: templates.json, patterns.json and tests.json.

Do not edit configuration files manually! Use one of Web2Cit editing tools instead.

This article has been copied and slightly adapted from archived Early adopters guideline for technical documentation purposes only.

이 문서의 일부 개념은 유튜브의 Web2Cit 얼리 어답터를 위한 이론적인 동영상에서 다룹니다.

위치

도메인 구성 파일은 최상위 도메인에서 마지막 하위 도메인에 이르기까지 호스트명 레이블당 하나의 하위 디렉토리인 Web2Cit/data/로 메타에 있습니다.

여기에서 구성 파일의 전체 목록을 찾을 수 있습니다.

예를 들어 호스트 이름 meta.wikimedia.org의 경우 구성 파일은 Web2Cit/data/org/wikimedia/meta/입니다.

URL 체계(예: http, https 등), 포트 및 경로는 호스트 이름의 일부가 아닙니다(T315020 참조). 예를 들어 URL https://meta.wikimedia.org/wiki/Web2Cit/Early_adopters#Domain_configuration_files의 경우 meta.wikimedia.org만 호스트명입니다.

도메인당 3개의 구성 파일이 있습니다: templates.json(번역 틀용), patterns.json(URL 경로 패턴용), tests.json(번역 테스트용). 예를 들어, meta.wikimedia.org에 대한 번역 틀 구성 파일은 Web2Cit/data/org/wikimedia/meta/templates.json가 됩니다.

Redirects

Redirects between configuration files are useful for domain aliases. For example, if www.example.com is an alias of example.com, configuration files of the former may be redirected to those of the latter so that the Web2Cit community does not have to maintain separate copies of the same files.

These redirects are followed both by Web2Cit core and by the JSON editor. Read the Domain aliases section of the Editing documentation for more information.

형식

모든 도메인 구성 파일은 JSON 형식으로 작성됩니다(대체 형식은 아래 참조).

일반적으로 JSON 파일에는 다음 "값" 유형의 조합이 있을 수 있습니다:

텍스트 문자열. 예를 들어 "xpath".^{[note 1]}
불리언 자료형: true 또는 false.
배열: 또는 쉼표로 구분된 0개 이상의 값이 있는 목록입니다. 예: [ "one", "two", "three" ].
객체: 쉼표로 구분된 0개 이상의 "키":값 쌍이 있습니다. 예를 들어:

{
  "key1": value1,
  "key2": value2
}

미디어위키 편집기는 JSON 파일 편집에 특화되어 있지 않습니다(페이지에 JSON 콘텐츠 모델이 없는 경우, T305571 참조). 별도의 편집기를 사용하여 편집한 다음 결과를 붙여넣는 것이 유용할 수 있습니다.

아래의 각 구성 파일에 대해 사용 가능한 예제 파일과 JSON 스키마 파일이 있습니다. JSON 스키마는 독립 실행형 유효성 검사기 또는 텍스트 편집기 통합을 사용하여 JSON 파일의 유효성을 검사하는 데 사용할 수 있습니다.^[1]

JSON 스키마 파일에서 생성된 간단한 형식을 통해 JSON 파일을 편집할 수 있는 json-editor,^[2]를 사용하는 것이 좋습니다(아래의 각 구성 파일 섹션에서 직접 링크 사용 가능).

기존 JSON 파일을 편집하는 경우 오른쪽에 있는 json-editor의 "JSON 출력" 필드에 붙여넣고 "양식 업데이트"를 클릭합니다.
양식을 작성하세요.
필드의 JSON 출력을 오른쪽으로 복사하여 메타에 붙여 넣습니다.

templates.json

templates.json 파일은 루트에 Template 개체의 배열을 포함합니다.

`Template` 객체

각 Template 객체는 "번역 틀"을 나타내며 일련의 세 가지 키:값 쌍을 갖습니다:

현재 도메인에서 번역 틀로 사용되는 웹페이지의 경로를 나타내는 문자열이 있는 path 키(path 값이 동일한 여러 Template 객체는 무시됨). 호스트명을 포함하지 마세요. /로 시작하는 경로입니다. 쿼리(?) 구성 요소를 포함할 수도 있습니다. 예를 들어 틀 웹페이지 https://example.com/news/article?id=3, /news/article?id=3를 사용합니다.
이 "번역 템플릿"에 대한 (선택적) 멋진 이름을 나타내는 값으로 문자열이 있는 label 키.
fields 키, 값으로 TemplateField 객체 배열 포함. fieldname 값이 동일한 여러 TemplateField 객체(아래 참조)는 무시됩니다.

{
  "path": string,
  "label": string,
  "fields": TemplateField[]
}

기본 대체 틀의 틀 필드 배열을 사용자 정의 번역 틀의 기초로 사용할 수 있습니다.^{[note 2]}

`TemplateField` 객체

차례로, 각 TemplateField 객체는 "번역 템플릿"의 "템플릿 필드"를 나타내며 일련의 세 가지 키:값 쌍을 갖습니다.

"틀 필드"의 이름을 나타내는 문자열을 값으로 포함하는 fieldname 키. 현재 지원되는 값은 필드 문서를 참조하세요.
required 키, 불리언 값(true 또는 false)으로 틀 필드가 필수로 표시되어야 하는지 여부를 나타냅니다. 틀 문서를 참조하세요.
Procedure 객체의 배열을 값으로 사용하는 procedures 키.

{
  "fieldname": string,
  "required": boolean,
  "procedures": Procedure[]
}

`Procedure` 객체

차례로 각 Procedure 객체는 "번역 절차"를 나타내며 일련의 두 가지 키:값 쌍을 갖습니다:

Selection 객체의 배열을 값으로 사용하는 selections 키.
Transformation 객체의 배열을 값으로 사용하는 transformations 키.

{
  "selections": Selection[],
  "transformations": Transformation[]
}

`Selection` 객체

각 Selection 객체는 "선택 단계"를 나타내며 두 개의 키:값 쌍으로 구성됩니다:

특정 유형의 "선택 단계"를 나타내는 값으로 문자열이 있는 type 키. 현재 지원되는 값은 틀 설명서의 선택 단계 하위 섹션을 참조하세요.
config 키(값으로 문자열 포함)^{[note 3]}는 선택 단계의 특정 구성을 나타냅니다. 현재 지원되는 값은 틀 설명서의 "선택 단계" 하위 섹션을 참조하세요.

{
  "type": string,
  "config": string
}

`Transformation` 객체

마지막으로 각 Transformation 객체는 "변환 단계"를 나타내며 일련의 세 가지 키:값 쌍을 갖습니다:

특정 유형의 변환 단계를 나타내는 값으로 문자열이 있는 type 키. 현재 지원되는 값은 틀 설명서의 "변환 단계" 하위 섹션을 참조하세요.
변환 단계에 대한 특정 구성을 나타내는 값으로 문자열이 있는 config 키^{[note 3]}. 현재 지원되는 값은 틀 설명서의 "변환 단계" 하위 섹션을 참조하세요.
itemwise 키, 불리언 값(true 또는 false)이 입력의 각 항목에 독립적으로 적용되어야 하는지(true) 아니면 전체 입력에 전체(false) 적용되어야 하는지를 나타냅니다.

{
  "type": string,
  "config": string
  "itemwise": boolean
}

patterns.json

patterns.json 파일은 루트에 Pattern 객체의 배열을 포함합니다.

`Pattern` 객체

각 Pattern은 "URL 경로 패턴"을 나타내며 두 개의 키:값 쌍으로 구성됩니다:

URL 일치 그룹을 정의하는 글로브 경로 패턴을 나타내는 값으로 문자열이 있는 pattern 키
이 "URL 경로 패턴"에 대한 (선택 사항) 멋진 이름을 나타내는 값으로 문자열이 있는 label 키:

{
  "pattern": string,
  "label": string
}

tests.json

tests.json 파일은 루트에 Test 객체의 배열을 포함합니다.

`Test` 객체

각 Test 객체는 "번역 테스트"를 나타내며 두 개의 키:값 쌍으로 구성됩니다:

현재 도메인에서 "번역 테스트"로 사용되는 웹 페이지의 "경로"를 나타내는 문자열이 있는 path 키(같은 path 값을 가진 여러 Test 객체는 무시됩니다). Template 객체의 path 속성과 마찬가지로 호스트 이름을 포함하지 않고 경로가 /로 시작하는지 확인합니다. 쿼리(?) 구성 요소를 포함할 수도 있습니다.
fields 키, 값으로 TestField 객체 배열 포함. fieldname 값이 동일한 여러 TestField 객체(아래 참조)는 무시됩니다.

{
  "path": string,
  "fields": TestField[]
}

`TestField` 객체

각 TestField 객체는 "번역 테스트"의 "테스트 필드"를 나타내며 두 개의 키:값 쌍으로 구성됩니다:

"필드 이름" 키: 번역 필드 이름이 지원됩니다.
"목표" 값: 주어진 번역 필드에 대한 예상 번역 출력 또는 "번역 목표"를 나타내는 문자열 배열. 각 문자열 값은 번역 필드의 Web2Cit/Docs/Fields유효성 검사 규칙을 준수해야 합니다. 출력이 예상되지 않음을 명시적으로 표현하려면 빈 배열을 제공하세요.

{
  "fieldname": string,
  "goal": string[]
}

대체 형식

JSON5 또는 YAML과 같이 사람이 읽을 수 있는 대체 형식을 사용하면 구성 파일을 수동으로 읽고 쓰는 데 도움이 될 수 있습니다. 작업 T302694에서 추적되는 것처럼 미래에 지원할 수도 있지만 현재는 이들 중 어느 것도 지원하지 않습니다.

지금은 온라인 변환기를 사용하여 다음을 수행할 수 있습니다:^{[note 4]}

JSON 구성 파일을 JSON5 또는 YAML로 변환
JSON5 또는 YAML에서 구성 파일 편집
JSON으로 다시 변환하고 JSON 스키마로 검증(위 참조)
JSON으로 구성 파일 저장

JSON5

JSON5^[3]는 JSON과 매우 유사하지만 더 유연하므로 몇 가지 일반적인 JSON 실수를 허용합니다. 우리의 경우 다음 기능이 흥미로울 수 있습니다:

키는 인용되지 않을 수 있습니다: { unquoted: "value" }
문자열은 작은따옴표로 묶을 수 있으며 그 안에 큰따옴표를 사용할 수 있습니다: 'single "quoted" string'
객체 및 배열의 후행 쉼표는 괜찮습니다: { key1: value1, key2: value2, } [ a, b, c, ]

YAML

YAML은 들여쓰기 기반(파이썬 문법 언어와 같은)이며 훨씬 짧고 (일반적으로)^[4] 쓰기 및 읽기가 더 쉽습니다.

다음은 발췌한 예제 템플릿 구성 파일의 JSON 및 YAML 버전을 나란히 비교한 것입니다:

[
  {
    "path": "/",
    "label": "fancy name",
    "fields": [
      {
        "fieldname": "title",
        "required": true,
        "procedures": [
          {
            "selections": [
              {
                "type": "citoid",
                "config": "title"
              }, {
                ...
              }
            ],
            "transformations": [
              {
                "type": "range",
                "config": "0",
                "itemwise": false
              },
              {
                ...
              }
            ]
          }
        ]
      },
      {
        "fieldname": "itemType",
        ...
      }
    ]
  },
  {
    ...
  }
]

- path: /
  label: fancy name
  fields:
    - fieldname: title
      required: true
      procedures:
        - selections:
          - type: citoid
            config: title
          - ...
          transformations:
          - type: range
            config: '0'
            itemwise: false
          - ...
    - fieldname: itemType
      ...
- ...

TemplateField 객체의 procedures 키는 각각 selections 및 transformations 키가 있는 Procedure 객체의 배열을 값으로 사용합니다. 따라서 다음 코드는 두 개의 개별 Procedure 객체를 지정하기 때문에 잘못된 것입니다. 하나는 selections 키이고 다른 하나는 transformations 키입니다:

...
        "procedures": [
          {
            "selections": [
              {
                "type": "citoid",
                "config": "title"
              }
            ]
          },
          {
            "transformations": [
              {
                "type": "range",
                "config": "0",
                "itemwise": false
              }
            ]
          }
...

...
      procedures:
        - selections:
          - type: citoid
            config: title
        - transformations:
          - type: range
            config: 0
            itemwise: false
...

Notes

↑ 텍스트 문자열은 큰따옴표 "로 시작하고 끝납니다. 따라서 내부에 큰따옴표를 사용하지 마십시오. 예를 들어, "some "quoted" text"에서는 문자열이 시작하거나 끝나는 위치가 명확하지 않습니다. 가능한 경우 큰따옴표를 작은따옴표 '으로 바꾸세요: "some 'quoted' text". 또는 /를 사용하여 내부 큰따옴표를 "escape": "some /"quoted/" text".
↑ Web2Cit Core의 소스 코드 저장소에서 사용할 수 있는 현재 사용되는 대체 틀 정의는 여기
↑ ^a ^b 대신 구성 값 배열을 사용하는 제안은 T305903을 참조하세요.
↑ 예를 들어 toolkit.site의 데이터 형식 변환기

References

[1] 텍스트 문자열은 큰따옴표 "로 시작하고 끝납니다. 따라서 내부에 큰따옴표를 사용하지 마십시오. 예를 들어, "some "quoted" text"에서는 문자열이 시작하거나 끝나는 위치가 명확하지 않습니다. 가능한 경우 큰따옴표를 작은따옴표 '으로 바꾸세요: "some 'quoted' text". 또는 /를 사용하여 내부 큰따옴표를 "escape": "some /"quoted/" text".

[4] Web2Cit Core의 소스 코드 저장소에서 사용할 수 있는 현재 사용되는 대체 틀 정의는 여기

[T305903-5] 대신 구성 값 배열을 사용하는 제안은 T305903을 참조하세요.

[6] 예를 들어 toolkit.site의 데이터 형식 변환기

[2] ttps://json-schema.org/implementations.html

[3] ttps://github.com/json-editor/json-editor

[7] ttps://json5.org/

[8] "YAML: probably not so great after all".

[note 1]

[1]

[2]

[note 2]

[note 3]

[note 4]

[3]

[4]

Web2Cit/Docs/Storage

위치

Redirects

형식

templates.json

Template 객체

TemplateField 객체

Procedure 객체

Selection 객체

Transformation 객체