프로젝트에 다국어 지원을 통한 글로벌 전시회 준비[Angular/다국어/@ngx-translate]

김유현·2024년 5월 9일

@ngx-translate/core Angular frontend i18n 국제화 다국어지원

오늘 소개할 내용은 미국의 유명 전시회에 참여하기 위해 프로덕트에 다국어 기능을 적용한 과정을 공유하고자 함
Angular와 함께 @ngx-translate/core 및 i18n을 활용하여 어떻게 한국어와 영어 버전을 구현했는지, 그리고 이 과정에서 얻은 경험을 나누고자 한다.

참조: ngx-translate 공식 문서

우선 @ngx-translate/core 라이브러리를 사용하여 앵귤러 프로젝트에서 다국어 처리를 구현하는 과정을 단계별로 작성해보겠다.

`@ngx-translate/core`란?

Angular 프레임워크를 사용하는 애플리케이션에서 국제화(i18n)를 지원하는 라이브러리
사용자는 JSON 형식으로 번역 파일을 만들고, @ngx-translate/core를 통해 애플리케이션에 적용하여 언어를 쉽게 전환할 수 있음

1단계: @ngx-translate/core 설치

npm install @ngx-translate/core @ngx-translate/http-loader

@ngx-translate/http-loader는 Angular HTTP 클라이언트를 사용하여 번역 파일을 로드하는 데 필요함.

2단계: AppModule 설정

app.module.ts 파일에서 TranslateModule과 HttpClientModule을 import하고 설정
이는 앱 전역에서 번역 기능을 사용할 수 있게한다.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

// TranslateModule과 HttpClientModule import
import { TranslateModule, TranslateLoader } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';
import { HttpClientModule, HttpClient } from '@angular/common/http';

// TranslateHttpLoader를 사용하여 외부 json 파일로부터 번역을 로드하는 팩토리 함수 생성
export function HttpLoaderFactory(http: HttpClient) {
  return new TranslateHttpLoader(http);
}

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    HttpClientModule,
    TranslateModule.forRoot({
      loader: {
        provide: TranslateLoader,
        useFactory: HttpLoaderFactory,
        deps: [HttpClient]
      }
    })
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

위위 코드는 기본적으로 번역 관련 모듈을 가져오는 작업을 포함하고 있다. 추가로, HttpLoaderFactory라는 팩토리 함수를 사용하여 TranslateModule 에 번역 로더 인스턴스를 생성하도록 설정했다. 이 설정 덕분에 각 서비스나 컴포넌트 파일에서 아래와 같이 번역 로더를 직접 생성하는 로직을 줄일 수 있었다.

// 팩토리 함수를 적용하지 않았을 경우 필요한 생성 로직
constructor(private http: HttpClient) {
    const translateLoader = new TranslateHttpLoader(this.http);
    // 이제 translateLoader를 사용할 수 있습니다.
}

3단계: 번역 파일 생성

src/assets/i18n/ 디렉토리를 생성하고, 각 언어별 JSON 파일을 만들어야 한다.
(예: en.json, ko.json). 각 파일에는 번역하고자 하는 문자열의 키-값 쌍을 포함해야한다.

예를 들어:

en.json

{
  "DASHBOARD": "Dashboard",
  "LEAK": "Leak",
  "SUPPLY": "Supply",
  "REMOTE": "Remote",
  "PIPE": "Pipe",
  "QUALITY": "Quality",
  "WATER_IMPACT": "Water Impact",
  "EPANET": "EPANET",
  "PROJECT": "Project",
  "SELECT_ZONE": "Select Zone"
}

ko.json

{
  "DASHBOARD": "대시보드",
  "LEAK": "누수",
  "SUPPLY": "급수",
  "REMOTE": "원격",
  "PIPE": "관로",
  "QUALITY": "수질",
  "WATER_IMPACT": "수충격",
  "EPANET": "EPANET",
  "PROJECT": "프로젝트",
  "SELECT_ZONE": "구역선택"
}

다국어 적용 작업을 거의 마무리하고 깨달은 사실은, 페이지별로 키를 구분하여 작성하는 방법이 향후 유지보수 측면에서 더욱 효율적이라는 것이다.

예를 들어, ko.json을 다음과 같이 수정하여 각 페이지에 따라 번역 키를 그룹화할 수 있다.

{
  Monitoring_page : {
  	"DASHBOARD": "대시보드",
    "LEAK": "누수",
    "SUPPLY": "급수",
    "REMOTE": "원격",
    "PIPE": "관로",
    "QUALITY": "수질",
    "WATER_IMPACT": "수충격",
    "EPANET": "EPANET",
    "PROJECT": "프로젝트",
    "SELECT_ZONE": "구역선택"
  }
  Another_page : {
  	"DASHBOARD": "다른 페이지 대시보드"
  }
}

이렇게 페이지별로 구성을 변경함으로써, 각 페이지에서 필요한 번역만을 불러와 사용할 수 있어, 더욱 체계적이고 효율적인 번역 관리가 가능해진다.

4단계: 컴포넌트에서 번역 사용하기

만약 웹 사이트에 존재하는 메뉴 텍스트들에 다국어를 적용하고자 가정하에 진행하겠다.

header-menu.component.ts 같은 컴포넌트 파일에서 TranslateService를 주입하고 초기 언어를 설정한다.

import { Component } from '@angular/core';
import { TranslateService } from '@ngx-translate/core';

@Component({
  selector: 'app-header-menu',
  templateUrl: './header-menu.component.html',
  styleUrls: ['./header-menu.component.scss']
})
export class HeaderMenuComponent {
  constructor(private translate: TranslateService) {
    // 사용 가능한 언어 설정
    translate.addLangs(['en', 'ko']);
    // 기본 언어 설정
    translate.setDefaultLang('ko');

    // 브라우저 언어로 설정하려면
    const browserLang = translate.getBrowserLang();
    translate.use(browserLang.match(/en|ko/) ? browserLang : 'ko');
  }
}

5단계: 템플릿에서 번역 사용하기

header-menu.component.html 같은 템플릿 파일에서 번역된 텍스트를 표시하려면
translate 파이프를 사용하면 된다.
아래 예시를 참고하자.

<p class="icon-caption">{{ 'DASHBOARD' | translate }}</p>
<p class="icon-caption">{{ 'LEAK' | translate }}</p>

이렇게 하면, 앵귤러 애플리케이션에서 다국어 처리를 위해 @ngx-translate/core 라이브러리를 성공적으로 사용할 수 있게 된다.

번외: 컴포넌트의 Typescript 코드 내에서 직접 번역을 처리할 필요가 있는 경우

Angular의 ngx-translate 라이브러리에서는 템플릿의 translate 파이프 외에도, 컴포넌트의 TypeScript 코드 내에서 직접 번역을 처리할 필요가 있는 경우 TranslateService의 instant 메소드를 사용할 수 있다

다음은 TranslateService의 instant 메소드를 사용하는 방법이다.

앞서 설명한 TranslateService가 컴포넌트 생성자에 주입이 되어있다는 가정 하에 진행하겠다.

@Component({
  // ...
})
export class MyComponent {
  translatedText: string;

  constructor(private translate: TranslateService) {
    this.translatedText = this.translate.instant('YOUR_TRANSLATION_KEY');
  }
}

※주의 사항※

instant 메소드는 번역 파일이나 키가 로드되지 않은 상태에서 호출되면 기대하는 번역 값을 제공하지 않을 수 있습니다. 이러한 경우, 번역 파일이 완전히 로드되고 나서 번역을 시도하거나, get 메소드를 사용하여 비동기적으로 번역 값을 요청해야한다.
언어 파일이나 어플리케이션이 초기화될 때까지 기다린 후 instant를 호출하는 것이 좋다