Getting Started Internationalizing (i18n) with Intlayer and React Create App
What is Intlayer?
Intlayer는 현대 웹 애플리케이션에서 다국적 지원을 간소화하기 위해 설계된 혁신적인 오픈 소스 국제화(i18n) 라이브러리입니다.
Intlayer를 사용하면:
- 구성 요소 수준에서 선언적 사전을 사용하여 번역을 쉽게 관리할 수 있습니다.
- 메타데이터, 경로 및 콘텐츠를 동적으로 지역화할 수 있습니다.
- 자동 생성된 유형으로 TypeScript 지원을 보장하여 자동 완성과 오류 감지를 개선합니다.
- 동적 로케일 감지 및 전환과 같은 고급 기능을 이용할 수 있습니다.
Step-by-Step Guide to Set Up Intlayer in a React Application
Step 1: Install Dependencies
npm을 사용하여 필요한 패키지를 설치합니다:
bash
1npm install intlayer react-intlayerbash
1yarn add intlayer react-intlayerbash
1pnpm add intlayer react-intlayerStep 2: Configuration of your project
애플리케이션의 언어를 구성하기 위해 구성 파일을 만듭니다:
typescript
1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6 internationalization: {
7 locales: [
8 Locales.ENGLISH,
9 Locales.FRENCH,
10 Locales.SPANISH,
11 // 기타 로케일 추가
12 ],
13 defaultLocale: Locales.ENGLISH,
14 },
15};
16
17export default config;사용 가능한 모든 매개변수를 보려면 구성 문서 여기 참조.
Step 3: Integrate Intlayer in Your CRA Configuration
react-intlayer를 사용하기 위해 스크립트를 변경합니다.
json
1 "scripts": {
2 "build": "react-intlayer build",
3 "start": "react-intlayer start",
4 "transpile": "intlayer build"
5 },참고: react-intlayer 스크립트는 craco를 기반으로 합니다. intlayer craco 플러그인을 기반으로 자체 설정을 구현할 수도 있습니다. 여기 예제 보기.
Step 4: Declare Your Content
콘텐츠 사전을 생성하고 관리합니다:
tsx
1// src/app.content.tsx
2import { t, type DeclarationContent } from "intlayer";
3import { type ReactNode } from "react";
4
5const appContent = {
6 key: "app",
7 content: {
8 getStarted: t<ReactNode>({
9 en: (
10 <>
11 Edit <code>src/App.tsx</code> and save to reload
12 </>
13 ),
14 fr: (
15 <>
16 Éditez <code>src/App.tsx</code> et enregistrez pour recharger
17 </>
18 ),
19 es: (
20 <>
21 Edita <code>src/App.tsx</code> y guarda para recargar
22 </>
23 ),
24 }),
25 reactLink: {
26 href: "https://reactjs.org",
27 content: t({
28 en: "Learn React",
29 fr: "Apprendre React",
30 es: "Aprender React",
31 }),
32 },
33 },
34} satisfies DeclarationContent;
35
36export default appContent;여기에서 Intlayer 선언 파일을 선언하는 방법 보기.
Step 5: Utilize Intlayer in Your Code
애플리케이션 전체에서 콘텐츠 사전에 접근합니다:
tsx
1import logo from "./logo.svg";
2import "./App.css";
3import { IntlayerProvider, useIntlayer } from "react-intlayer";
4import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
5
6function AppContent() {
7 const content = useIntlayer("app");
8
9 return (
10 <header className="App-header">
11 <img src={logo} className="App-logo" alt="logo" />
12
13 {content.getStarted}
14 <a
15 className="App-link"
16 href={content.reactLink.href.value}
17 target="_blank"
18 rel="noopener noreferrer"
19 >
20 {content.reactLink.content}
21 </a>
22 </header>
23 );
24}
25
26function App() {
27 return (
28 <IntlayerProvider>
29 <div className="App">
30 {/* useIntlayer 훅을 올바르게 사용하려면 자식 구성 요소에서 데이터를 접근해야 합니다 */}
31 <AppContent />
32 </div>
33 <div className="absolute bottom-5 right-5 z-50">
34 <LocaleSwitcher />
35 </div>
36 </IntlayerProvider>
37 );
38}
39
40export default App;참고: alt, title, href, aria-label 등과 같은 string 속성에서 콘텐츠를 사용하려면, 함수의 값을 호출해야 합니다, 예를 들면:
tsx1<img src={content.image.src.value} alt={content.image.value} />
(Optional) Step 6: Change the language of your content
콘텐츠의 언어를 변경하려면 useLocale 훅에서 제공하는 setLocale 함수를 사용할 수 있습니다. 이 함수는 애플리케이션의 로케일을 설정하고 콘텐츠를 적절히 업데이트합니다.
tsx
1import { Locales } from "intlayer";
2import { useLocale } from "react-intlayer";
3
4const LocaleSwitcher = () => {
5 const { setLocale } = useLocale();
6
7 return (
8 <button onClick={() => setLocale(Locales.English)}>
9 Change Language to English
10 </button>
11 );
12};(Optional) Step 7: Add localized Routing to your application
이 단계의 목적은 각 언어에 대한 고유한 경로를 만드는 것입니다. 이는 SEO와 SEO 친화적인 URL에 유용합니다. 예시:
tsx
1// /dashboard
2// /es/dashboard
3// /fr/dashboard기본적으로 경로는 기본 로케일에 대해 접두사가 없습니다. 기본 로케일에 접두사를 추가하려면 구성에서 middleware.prefixDefault 옵션을 true로 설정할 수 있습니다. 구성 문서 참조에서 더 많은 정보를 얻을 수 있습니다.
앱에 지역화된 라우팅을 추가하려면, 애플리케이션의 경로를 감싸고 로케일 기반 라우팅을 처리하는 LocaleRouter 구성 요소를 만들 수 있습니다. 다음은 React Router를 사용한 예시입니다:
tsx
1// 필요한 종속성 및 함수 가져오기
2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // 'intlayer'에서 유틸리티 함수 및 유형 가져오기
3import { FC, PropsWithChildren } from "react"; // 기능 구성 요소 및 소품을 위한 React 유형
4import { IntlayerProvider } from "react-intlayer"; // 국제화 컨텍스트를 위한 제공자
5import {
6 BrowserRouter,
7 Routes,
8 Route,
9 useParams,
10 Navigate,
11 useLocation,
12} from "react-router-dom"; // 탐색 관리를 위한 라우터 구성 요소
13
14// Intlayer에서 구성 분해
15const { internationalization, middleware } = getConfiguration();
16const { locales, defaultLocale } = internationalization;
17
18/**
19 * 로컬화 관리를 처리하는 구성 요소.
20 * URL 기반 로케일 감지 및 유효성 검사를 처리합니다.
21 */
22const AppLocalized: FC<PropsWithChildren> = ({ children }) => {
23 const path = useLocation().pathname; // 현재 URL 경로 가져오기
24 const { locale } = useParams<{ locale: Locales }>(); // URL에서 로케일 매개변수 추출
25
26 // 현재 로케일 결정, 제공되지 않을 경우 기본값으로 되돌아감
27 const currentLocale = locale ?? defaultLocale;
28
29 // 경로에서 로케일 접두사를 제거하여 기본 경로 구성
30 const pathWithoutLocale = removeLocaleFromUrl(
31 path // 현재 URL 경로
32 );
33
34 /**
35 * middleware.prefixDefault가 true이면 기본 로케일은 항상 접두사가 있어야 합니다.
36 */
37 if (middleware.prefixDefault) {
38 // 로케일 유효성 검사
39 if (!locale || !locales.includes(locale)) {
40 // 업데이트된 경로로 기본 로케일로 리디렉션
41 return (
42 <Navigate
43 to={`/${defaultLocale}/${pathWithoutLocale}`}
44 replace // 현재 기록 항목을 새 항목으로 대체
45 />
46 );
47 }
48
49 // IntlayerProvider로 자식을 감싸고 현재 로케일 설정
50 return (
51 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
52 );
53 } else {
54 /**
55 * middleware.prefixDefault가 false일 때, 기본 로케일은 접두사가 없습니다.
56 * 현재 로케일이 유효하며 기본 로케일이 아닌지 확인합니다.
57 */
58 if (
59 currentLocale.toString() !== defaultLocale.toString() &&
60 !locales
61 .filter(
62 (locale) => locale.toString() !== defaultLocale.toString() // 기본 로케일 제외
63 )
64 .includes(currentLocale) // 현재 로케일이 유효한 로케일 목록에 있는지 확인
65 ) {
66 // 로케일 접두사 없이 경로로 리디렉션
67 return <Navigate to={pathWithoutLocale} replace />;
68 }
69
70 // IntlayerProvider로 자식을 감싸고 현재 로케일 설정
71 return (
72 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
73 );
74 }
75};
76
77/**
78 * 로케일별 경로를 설정하는 라우터 구성 요소.
79 * React Router를 사용하여 탐색을 관리하고 지역화된 구성 요소를 렌더링합니다.
80 */
81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
82 <BrowserRouter>
83 <Routes>
84 <Route
85 // 로케일을 캡처하는 경로 패턴 (예: /en/, /fr/) 및 모든 이후 경로와 일치
86 path="/:locale/*"
87 element={<AppLocalized>{children}</AppLocalized>} // 로케일 관리를 위한 자식으로 감싸기
88 />
89
90 {
91 // 기본 로케일 접두사가 비활성화된 경우 루트 경로에서 직접 자식을 렌더링
92 !middleware.prefixDefault && (
93 <Route
94 path="*"
95 element={<AppLocalized>{children}</AppLocalized>} // 로케일 관리를 위한 자식으로 감싸기
96 />
97 )
98 }
99 </Routes>
100 </BrowserRouter>
101);(Optional) Step 8: Change the URL when the locale changes
로케일이 변경될 때 URL을 변경하려면, useLocale 훅에서 제공하는 onLocaleChange 속성을 사용할 수 있습니다. 동시에, react-router-dom의 useLocation 및 useNavigate 훅을 사용하여 URL 경로를 업데이트할 수 있습니다.
tsx
1import { Locales, getLocalizedUrl } from "intlayer";
2import { useLocale } from "react-intlayer";
3import { useLocation, useNavigate } from "react-router-dom";
4
5const LocaleSwitcher = () => {
6 const location = useLocation(); // 현재 URL 경로 가져오기. 예: /fr/about
7 const navigate = useNavigate();
8
9 const changeUrl = (locale: Locales) => {
10 // 업데이트된 로케일로 URL 구성
11 // 예: 로케일이 스페인어로 설정될 때 /es/about
12 const pathWithLocale = getLocalizedUrl(location.pathname, locale);
13
14 // URL 경로 업데이트
15 navigate(pathWithLocale);
16 };
17
18 const { setLocale } = useLocale({
19 onLocaleChange: changeUrl,
20 });
21
22 return (
23 <button onClick={() => setLocale(Locales.English)}>
24 Change Language to English
25 </button>
26 );
27};Configure TypeScript
Intlayer는 모듈 증강을 사용하여 TypeScript의 이점을 얻고 코드베이스를 더 강력하게 만듭니다.
TypeScript 구성이 자동 생성된 유형을 포함하도록 설정되어 있는지 확인합니다.
json5
1// tsconfig.json
2
3{
4 // 사용자 정의 구성
5 include: [
6 "src",
7 "types", // <- 자동 생성된 유형 포함
8 ],
9}Git Configuration
Intlayer 의해 생성된 파일을 무시하는 것이 좋습니다. 이를 통해 Git 리포지토리에 파일을 커밋하지 않도록 할 수 있습니다.
이를 위해 .gitignore 파일에 다음 지침을 추가할 수 있습니다:
gitignore
1# Intlayer 의해 생성된 파일 무시
2.intlayer이 문서를 개선할 아이디어가 있으시면 GitHub에 풀 리퀘스트를 제출하여 자유롭게 기여해 주세요.
문서에 대한 GitHub 링크