콘텐츠로 건너뛰기
Lunaria

대시보드 사용자 지정

Lunaria는 프로젝트의 외관과 느낌에 맞게 로컬라이제이션 대시보드를 다양한 방식으로 사용자 지정할 수 있도록 제공합니다. 다음 가이드를 따라 사용 가능한 모든 사용자 지정 옵션을 이해하세요.

제목 및 설명

기본적으로, Lunaria는 대시보드에 기본 제목과 설명을 추가합니다. 검색 엔진을 통해 프로젝트의 대시보드를 쉽게 식별하고 찾을 수 있도록 변경할 수 있습니다.

  1. Lunaria 설정 파일에 dashboard.title 옵션을 추가하세요. 정의된 제목은 대시보드의 제목에도 표시됩니다:

    lunaria.config.json
    {
      "dashboard": {
        "title": "Lunaria 로컬라이제이션 상태"
      }
    }

  2. dashboard.description 옵션을 당신의 Lunaria 설정 파일에 추가하세요:

    lunaria.config.json
     {
       "dashboard": {
         "title": "Lunaria 로컬라이제이션 상태",
         "description": "Lunaria 프로젝트용 로컬라이제이션 상태 대시보드."
       }
     }

상징적 URL

대시보드의 다른 버전(예: 대시보드 자체의 로컬라이제이션 버전)을 공개하고 싶다면, 검색 엔진에서 대시보드의 순위를 최적화하기 위해 상징적 URL을 설정하는 것이 유용할 수 있습니다.

상징적 URL을 추가하려면, 자신의 Lunaria 구성 파일에서 dashboard.site를 설정하면 됩니다:

lunaria.config.json
{
  "dashboard": {
    "site": "https://localization.lunaria.dev/"
  }
}

파비콘

파비콘을 설정하면 프로젝트의 분위기에 맞추고 사용자의 웹 브라우저에서 대시보드를 더 쉽게 식별할 수 있습니다. Lunaria는 여러 개의 외부 파비콘과 하나의 인라인 파비콘을 정의할 수 있게 허용합니다.

파비콘을 추가하려면, 자신이 선택한 외부 또는 인라인 속성 중 하나 이상을 사용해 dashboard.favicon을 설정해야 합니다.

외부 파비콘

외부 파비콘은 다른 URL을 통해 리소스로 불러오는 파비콘입니다. dashboard.favicon의 외부 속성에 추가할 수 있습니다. 아래 예시에서는 .svg와 .ico 파비콘을 모두 추가합니다.

lunaria.config.json
{
  "dashboard": {
    "favicon": {
      "external": [
        {
          "link": "https://lunaria.dev/favicon.svg",
          "type": "image/svg+xml"
        },
        {
          "link": "https://lunaria.dev/favicon.ico",
          "type": "image/x-icon"
        },
      ]
    }
  }
}

인라인 파비콘

인라인 파비콘은 데이터 URI를 통해 대시보드에 직접 추가되는 로컬 .svg 파비콘입니다. dashboard.favicon의 인라인 속성을 통해 추가할 수 있습니다.

  1. 프로젝트 내 디렉터리(예: src/assets/)에 파비콘 SVG 파일을 추가하세요:

    • 디렉토리src/
      • 디렉토리assets/
        • favicon.svg
    • lunaria.config.json

  2. 자신이 생성한 파비콘 경로를, 자신의 lunaria.config.json 파일에서 dashboard.favicon의 인라인 속성에 추가하세요:

    lunaria.config.json
    {
      "dashboard": {
        "favicon": {
          "inline": "./src/assets/favicon.svg"
        }
      }
    }

숨겨진 경로 기준

대시보드에는 소스 및 로컬라이제이션된 콘텐츠로 연결된 몇 가지 경로가 포함되어 있습니다. 이러한 경로는 프로젝트 루트 디렉터리로부터 얼마나 멀리 떨어져 있는지에 따라 매우 길어질 수 있습니다. 예를 들어, 콘텐츠 파일의 경로에서 src/content/docs/ 이후부터 유일한 부분이 시작된다면, 이 일부 경로를 숨기고 관련된 부분만 표시하는 것이 좋습니다. 예: guides/my-content.mdx.

이 작업을 수행하려면, 자신의 lunaria.config.json 파일에서 dashboard.basesToHide 옵션을 설정하여 숨기고 싶은 모든 경로 기준을 나열하세요. 이 예시는 src/content/docs/ 또는 src/i18n/에서 시작하는 콘텐츠 파일을 추적한다고 가정합니다:

lunaria.config.json
{
  "dashboard": {
    "basesToHide": ["src/content/docs/", "src/i18n/"]
  }
}

이 설정을 하면 src/content/docs/guide.mdx 및 src/i18n/dictionary.ts와 같은 경로 참조가 고유한 부분인 guide.mdx와 dictionary.ts로 단축됩니다.

사용자 정의 CSS

사용자 정의 CSS를 추가함으로써 대시보드를 더욱 세부적으로 사용자 지정할 수 있으며, 기본적으로 제공되는 스타일을 수정하거나 확장할 수 있습니다.

  1. 프로젝트 내 디렉터리(예: src/styles/)에 새로운 CSS 파일을 추가하세요. 예를 들어, 기본 본문 글꼴을 변경할 수 있습니다:

    src/styles/lunaria.css
    :root {
        --ln-font-body: Tahoma, sans-serif;
    }

  2. 자신이 만든 CSS 파일의 경로를 lunaria.config.json 파일의 dashboard.customCss 배열 속성에 추가하세요:

    lunaria.config.json
    {
      "dashboard": {
        "customCss": ["./src/styles/lunaria.css"]
      }
    }

사용자 정의 레이블 및 언어

기본적으로, Lunaria 대시보드는 영어로 작성된 UI 레이블을 포함합니다. 이러한 UI 레이블은 단순한 텍스트 레이블, 언어 값, 또는 동적인 문장(예: “완료됨: X개, 오래됨: X개, 누락됨: X개”) 등으로 완전히 변경될 수 있습니다.

텍스트 레이블

예를 들어, 특정 지역의 로컬라이제이션이 100% 완료되었을 때 표시되는 기본 메시지를 변경하려면 dashboard.ui의 statusByLocale.completeLocalization 속성을 변경하면 됩니다:

lunaria.config.json
{
  "dashboard": {
    "ui": {
      "statusByLocale.completeLocalization": "누락되거나 오래된 변경 사항이 발견되지 않았습니다, 축하합니다!"
    }
  }
}

형식 레이블

이름에 Format이라는 접미사를 가진 일부 레이블은 {} 블록을 포함하며, 이 블록은 다른 UI 레이블이나 내부 컨텍스트의 값으로 동적으로 교체됩니다. 예:

"statusByLocale.detailsTitleFormat": "{locale_name} ({locale_tag})",

이런 레이블도 변경할 수 있지만, 기본적으로 존재하는 {} 블록을 삭제하는 것은 권장하지 않습니다. 왜냐하면 예상되는 동적 값을 삽입하지 못할 수 있기 때문입니다.

예를 들어, 기본 statusByLocale.detailsTitleFormat 값을 약간 수정하여 언어 세부 정보 요약을 Deutsch (de)에서 Deutsch - de로 표시하도록 대시보드를 수정할 수 있습니다:

lunaria.config.json
{
  "dashboard": {
    "ui": {
      "statusByLocale.detailsTitleFormat": "{locale_name} - {locale_tag}",
    }
  }
}

lang 및 dir

모든 레이블이 변경될 수 있으므로, 대시보드를 다른 언어로 완전히 번역할 필요는 없습니다. 이를 더 쉽게 만들기 위해 dashboard.ui는 lang 및 dir 속성을 노출하고 있으며, 이는 대시보드에서 사용되는 HTML lang 및 dir 속성에 직접 매핑됩니다.

예를 들어, 대시보드의 언어를 브라질 포르투갈어로 변경하려면 다음과 같이 설정할 수 있습니다(간단함을 위해 많은 속성이 생략되었습니다):

lunaria.config.json
{
  "dashboard": {
    "ui": {
      "lang": "pt-BR",
      "statusByFile.heading": "파일별 로컬라이제이션 상태",
      "statusByFile.tableRowFile": "파일",
    }
  }
}

사용자 정의 UI 요소

Lunaria의 대시보드는 사용자 정의 CSS와 사용 가능한 구성 옵션을 통해 유연하고 쉽게 사용자 지정될 수 있도록 설계되었습니다. 그러나 그것으로도 충분하지 않을 경우, 렌더러 API를 사용하여 대시보드의 UI를 확장하거나 재정의할 수 있습니다.

  1. 다음 내용을 포함하는 새 renderer.config.ts 또는 renderer.config.js 파일을 프로젝트에 추가하세요:

    renderer.config.ts
    import { defineRendererConfig } from '@lunariajs/core';
    

    export default defineRendererConfig({
      // 옵션은 여기에 입력됩니다...
    });

  2. 자신의 lunaria.config.json 파일의 renderer 구성 속성에 렌더러 파일의 경로를 추가하세요:

    lunaria.config.json
    {
      "renderer": "./renderer.config.ts"
    }

사용자 정의 컴포넌트

Lunaria의 모든 UI 요소는 프레임워크 없이 오직 전통적인 HTML만을 사용하여 구축됩니다. 작성을 쉽게 하기 위해, Lunaria는 자체적으로 html 태그 템플릿을 제공하여 사용자가 자신만의 컴포넌트를 만들 수 있도록 도와줍니다.

Lunaria의 컴포넌트는 몇 가지 매개변수를 받고 문자열 형태의 HTML을 반환하는 함수입니다:

example-component.ts
import { html } from '@lunariajs/core';


const CustomParagraph = () => html`<p>이것은 내 사용자 정의 단락 컴포넌트입니다!</p>`;

이 컴포넌트들은 템플릿 리터럴이므로, 일반적인 자바스크립트처럼 ${} 표기법을 사용하여 값을 삽입할 수 있습니다:

interpolating-value.ts
import { html } from '@lunariajs/core';


const favoriteColor = "red";


const ColorComponent = () => html`<p>내가 가장 좋아하는 색깔은 ${favoriteColor}입니다!</p>`.
결과로 나오는 HTML 보기
<p>내가 가장 좋아하는 색깔은 red입니다!</p>

또한 .map() 메서드를 사용하여 값 리스트(예: 배열)를 반복해서 삽입할 수도 있습니다:

interpolating-list.ts
import { html } from '@lunariajs/core';


const catColors = ["grey", "white", "black", "orange", "buff"];


const CatColorsList = () => html`<ul>${catColors.map((catColor) => html`<li>${catColor}</li>`)}</ul>`
결과로 나오는 HTML 보기
<ul>
  <li>grey</li>
  <li>white</li>
  <li>black</li>
  <li>orange</li>
  <li>buff</li>
</ul>

슬롯 요소

요소는 렌더러의 slots 속성을 통해 대시보드에 삽입될 수 있습니다. 모든 컴포넌트는 해당 구성의 복사본을 전달받으며, 이 복사본을 사용하여 값을 얻을 수 있습니다:

  1. html 태그 템플릿을 사용하여 새로운 컴포넌트를 만듭니다. 이 경우, 검색 엔진에서 대시보드를 인덱싱하지 않도록 하는 "noindex" 내용을 가진 "robots" 메타 태그를 생성합니다:

    renderer.config.ts
    import { defineRendererConfig, html } from '@lunariajs/core';
    

    const NoIndex = () => html`<meta name="robots" content="noindex" />`;
    

    export default defineRendererConfig({});

  2. 생성한 컴포넌트를 slots 속성에 있는 가능한 슬롯 중 하나에 추가하세요. 여기서는 head 슬롯을 사용하여 컴포넌트를 대시보드의 <head> 요소에 삽입합니다:

    renderer.config.ts
    import { defineRendererConfig, html } from '@lunariajs/core';
    

    const NoIndex = () => html`<meta name="robots" content="noindex" />`;
    

    export default defineRendererConfig({
      slots: {
        head: NoIndex,
      }
    });

요소 재정의

요소는 렌더러의 overrides 속성을 사용하여 대시보드에서 재정의할 수도 있습니다. overrides에 추가된 모든 컴포넌트는 구성의 복사본뿐만 아니라, 생성된 Lunaria 상태(단, meta 속성 제외)도 전달받아 값을 가져올 수 있습니다:

  1. html 태그 템플릿을 사용하여 새로운 컴포넌트를 만듭니다. 이 경우, 컴포넌트는 대시보드의 본문을 재정의하고 각 로컬라이제이션된 콘텐츠의 sharedPath를 표시합니다:

    renderer.config.ts
    import { defineRendererConfig, html } from '@lunariajs/core';
    

    const NewBody = (config, status) => html`<ul>${status.map((s) => html`<li>${s.sharedPath}</li>`)}</ul>`;
    

    export default defineRendererConfig({});

  2. 생성한 컴포넌트를 overrides 속성에 있는 가능한 재정의 항목 중 하나에 추가하세요. 여기서는 body 슬롯을 사용하여 컴포넌트를 삽입하고 대시보드의 <body> 요소 내부의 모든 내용을 재정의합니다:

    renderer.config.ts
    import { defineRendererConfig, html } from '@lunariajs/core';
    

    const NewBody = (config, status) => html`<ul>${status.map((s) => html`<li>${s.sharedPath}</li>`)}</ul>`;
    

    export default defineRendererConfig({
      overrides: {
        body: NewBody,
      }
    });