방법: 애플리케이션 지역화

아티클
05/04/2023

이 자습서에서는 LocBaml 도구를 사용하여 지역화된 애플리케이션을 만드는 방법을 설명합니다.

참고

LocBaml 도구는 프로덕션용 애플리케이션이 아닙니다. 지역화 API 중 일부를 사용하며 지역화 도구를 작성하는 방법을 설명하는 샘플로 제공됩니다.

개요

이 문서에서는 애플리케이션을 지역화하는 단계별 접근 방식을 제공합니다. 먼저 번역할 텍스트를 추출할 수 있도록 애플리케이션을 준비합니다. 텍스트를 번역한 후에 번역된 텍스트를 원래 애플리케이션의 새 복사본으로 병합합니다.

샘플 애플리케이션 만들기

이 단계에서는 지역화를 위해 앱을 준비합니다. WPF(Windows Presentation Foundation) 샘플에서는 이 설명의 코드 예제에 사용되는 HelloApp 샘플이 제공됩니다. 이 샘플을 사용하려면 LocBaml 도구 샘플에서 XAML(Extensible Application Markup Language) 파일을 다운로드합니다.

지역화를 시작하려는 지점까지 애플리케이션을 개발합니다.
MSBuild에서 주 어셈블리와 중립 언어 리소스가 포함될 위성 어셈블리(확장명이 .resources.dll인 파일)를 생성하도록 프로젝트 파일에서 개발 언어를 지정합니다. HelloApp 샘플의 프로젝트 파일은 HelloApp.csproj입니다. 해당 파일에서 다음과 같이 식별된 개발 언어를 찾을 수 있습니다.

<UICulture>en-US</UICulture>
XAML 파일에 Uid를 추가합니다. Uid는 파일의 변경 내용을 추적하고 번역해야 하는 항목을 식별하는 데 사용됩니다. 파일에 Uid를 추가하려면 프로젝트 파일에서 updateuid를 실행합니다.

msbuild -t:updateuid helloapp.csproj

누락되었거나 중복된 Uid가 없는지 확인하려면 checkuid를 실행합니다.

msbuild -t:checkuid helloapp.csproj

updateuid를 실행한 후 파일에 Uid가 포함되어야 합니다. 예를 들어, HelloApp의 Pane1.xaml 파일에서는 다음을 찾을 수 있습니다.
```
<StackPanel x:Uid="StackPanel_1">
  <TextBlock x:Uid="TextBlock_1">Hello World</TextBlock>
  <TextBlock x:Uid="TextBlock_2">Goodbye World</TextBlock>
</StackPanel>
```

중립 언어 리소스 위성 어셈블리 만들기

애플리케이션이 중립 언어 리소스 위성 어셈블리를 생성하도록 구성된 후 애플리케이션을 빌드합니다. 그러면 지역화를 위해 LocBaml에 필요한 중립 언어 리소스 위성 어셈블리와 주 애플리케이션 어셈블리가 생성됩니다.

애플리케이션을 빌드하려면:

HelloApp을 컴파일하여 DLL(동적 연결 라이브러리)을 만듭니다.

msbuild helloapp.csproj
새로 만든 주 애플리케이션 어셈블리인 HelloApp.exe는 다음 폴더(C:\HelloApp\Bin\Debug)에 만들어집니다.
새로 만든 중립 언어 리소스 위성 어셈블리인 HelloApp.resources.dll은 다음 폴더(C:\HelloApp\Bin\Debug\en-US)에 만들어집니다.

LocBaml 도구 빌드

LocBaml을 빌드하는 데 필요한 모든 파일은 WPF 샘플에 있습니다. LocBaml 도구 샘플에서 C# 파일을 다운로드합니다.
명령줄에서 프로젝트 파일(locbaml.csproj)을 실행하여 도구를 빌드합니다.

msbuild locbaml.csproj
Bin\Release 디렉터리로 이동하여 새로 만든 실행 파일(locbaml.exe)을 찾습니다. 예: C:\LocBaml\Bin\Release\locbaml.exe

LocBaml을 실행할 때 지정할 수 있는 옵션은 다음과 같습니다.

옵션	설명
`parse` 또는 `-p`	Baml, 리소스 또는 DLL 파일을 구문 분석하여 .csv 또는 .txt 파일을 생성합니다.
`generate` 또는 `-g`	번역된 파일을 사용하여 지역화된 이진 파일을 생성합니다.
`out` 또는 `-o` {filedirectory]	출력 파일 이름입니다.
`culture` 또는 `-cul` {culture]	출력 어셈블리의 로캘입니다.
`translation` 또는 `-trans` {translation.csv]	번역 또는 지역화된 파일입니다.
`asmpath` 또는 `-asmpath` {filedirectory]	XAML 코드에 사용자 지정 컨트롤이 포함된 경우 사용자 지정 컨트롤 어셈블리에 `asmpath`를 제공해야 합니다.
`nologo`	로고 또는 저작권 정보를 표시하지 않습니다.
`verbose`	자세한 정보 표시 모드 정보를 표시합니다.

참고

도구를 실행할 때 옵션 목록이 필요하면 LocBaml.exe를 입력한 다음, Enter 키를 누릅니다.

LocBaml을 사용하여 파일 구문 분석

LocBaml 도구를 만들었으므로 이제 이 도구를 통해 HelloApp.resources.dll을 구문 분석하여 지역화할 텍스트 콘텐츠를 추출할 준비가 되었습니다.

주 애플리케이션 어셈블리가 만들어진 애플리케이션의 bin\debug 폴더에 LocBaml.exe를 복사합니다.
위성 어셈블리 파일을 구문 분석하고 출력을 .csv 파일로 저장하려면 다음 명령을 사용합니다.

LocBaml.exe /parse HelloApp.resources.dll /out:Hello.csv

참고

입력 파일 HelloApp.resources.dll이 LocBaml.exe와 동일한 디렉터리에 없는 경우 두 파일이 동일한 디렉터리에 있도록 파일 중 하나를 이동합니다.

LocBaml을 실행하여 파일을 구문 분석하는 경우 출력은 쉼표(.csv 파일) 또는 탭(.txt 파일)으로 구분된 7개 필드로 구성됩니다. 다음은 HelloApp.resources.dll에 대해 구문 분석된 .csv 파일을 보여 줍니다.

구문 분석된 .csv 파일
HelloApp.g.en-US.resources:window1.baml,Stack1:System.Windows.Controls.StackPanel.$Content,Ignore,FALSE, FALSE,,#Text1;#Text2;
HelloApp.g.en-US.resources:window1.baml,Text1:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Hello World
HelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlock.$Content,None,TRUE, TRUE,,Goodbye World

7개 필드는 다음과 같습니다.

BAML 이름. 소스 언어 위성 어셈블리와 관련된 BAML 리소스의 이름입니다.
리소스 키. 지역화된 리소스 식별자입니다.
범주. 값 형식입니다. 지역화 특성 및 주석을 참조하세요.
가독성. 로컬라이저가 값을 읽을 수 있는지 여부입니다. 지역화 특성 및 주석을 참조하세요.
Modifiability 로컬라이저가 값을 수정할 수 있는지 여부입니다. 지역화 특성 및 주석을 참조하세요.
설명. 값은 지역화하는 방법을 확인하는 데 도움이 되는 값에 대한 추가 설명입니다. 지역화 특성 및 주석을 참조하세요.
값. 원하는 문화권으로 번역할 텍스트 값입니다.

다음 표에서는 이러한 필드가 .csv 파일의 구분된 값에 매핑되는 방법을 보여 줍니다.

BAML 이름	리소스 키	범주	가독성	수정 가능성	값
HelloApp.g.en-US.resources:window1.baml	Stack1:System.Windows.Controls.StackPanel.$Content	무시	FALSE	FALSE	#Text1;#Text2
HelloApp.g.en-US.resources:window1.baml	Text1:System.Windows.Controls.TextBlock.$Content	없음	TRUE	TRUE	Hello World
HelloApp.g.en-US.resources:window1.baml	Text2:System.Windows.Controls.TextBlock.$Content	없음	TRUE	TRUE	Goodbye World

주석 필드의 모든 값에는 값이 포함되어 있지 않습니다. 필드에 값이 없는 경우 비어 있습니다. 또한 첫 번째 행의 항목은 읽고 수정할 수 없으며 해당 범주 값으로 "무시"가 포함되어 값을 지역화할 수 없음을 나타냅니다.

구문 분석된 파일, 특히 큰 파일에서 지역화 가능한 항목의 검색이 용이하도록 범주, 가독성 및 수정 가능성을 기준으로 항목을 정렬하거나 필터링할 수 있습니다. 예를 들어 읽을 수 없는 값과 수정할 수 없는 값을 필터링할 수 있습니다.

지역화할 수 있는 콘텐츠 번역

사용 가능한 임의 도구를 사용하여 추출한 콘텐츠를 번역합니다. 이 작업을 효율적으로 수행하려면 .csv 파일에 리소스를 쓴 다음, Microsoft Excel에서 보고 마지막 열(값)에서 번역하는 것이 좋습니다.

LocBaml을 사용하여 새 .resources.dll 파일 생성

LocBaml로 HelloApp.resources.dll을 구문 분석하여 식별된 콘텐츠가 번역되었으며 원래 애플리케이션에 다시 병합해야 합니다. generate 또는 -g 옵션을 사용하여 새 .resources.dll 파일을 생성합니다.

다음 구문을 사용하여 새 HelloApp.resources.dll 파일을 생성합니다. 문화권을 en-US로 표시합니다(/cul:en-US).

LocBaml.exe /generate HelloApp.resources.dll /trans:Hello.csv /out:c:\ /cul:en-US

참고

입력 파일 Hello.csv가 LocBaml.exe 실행 파일과 동일한 디렉터리에 없는 경우 두 파일이 동일한 디렉터리에 있도록 파일 중 하나를 이동합니다.
C:\HelloApp\Bin\Debug\en-US\HelloApp.resources.dll 디렉터리에 있는 기존 HelloApp.resources.dll 파일을 새로 만든 HelloApp.resources.dll 파일로 바꿉니다.
이제 애플리케이션에서 "Hello World" 및 "Goodbye World"가 번역됩니다.
다른 문화권으로 번역하려면 번역할 대상 언어의 문화권을 사용합니다. 다음 예제에서는 프랑스어-캐나다로 번역하는 방법을 보여 줍니다.

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA
주 애플리케이션 어셈블리와 동일한 어셈블리에서 새 위성 어셈블리를 포함할 새 문화권별 폴더를 만듭니다. 프랑스어-캐나다의 경우 폴더는 fr-CA입니다.
생성된 위성 어셈블리를 새 폴더에 복사합니다.

새 위성 어셈블리를 테스트하려면 애플리케이션이 실행되는 문화권을 변경해야 합니다. 이 작업은 다음 두 가지 방법 중 한 가지로 수행할 수 있습니다.

운영 체제의 국가별 설정을 변경합니다.

애플리케이션에서 다음 코드를 App.xaml.cs에 추가합니다.

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="SDKSample.App"
    x:Uid="Application_1"
    StartupUri="Window1.xaml">
</Application>

using System.Windows;
using System.Globalization;
using System.Threading;

namespace SDKSample
{
    public partial class App : Application
    {
        public App()
        {
            // Change culture under which this application runs
            CultureInfo ci = new CultureInfo("fr-CA");
            Thread.CurrentThread.CurrentCulture = ci;
            Thread.CurrentThread.CurrentUICulture = ci;
        }
    }
}


Imports System.Windows
Imports System.Globalization
Imports System.Threading

Namespace SDKSample
    Partial Public Class App
        Inherits Application
        Public Sub New()
            ' Change culture under which this application runs
            Dim ci As New CultureInfo("fr-CA")
            Thread.CurrentThread.CurrentCulture = ci
            Thread.CurrentThread.CurrentUICulture = ci
        End Sub
    End Class
End Namespace

LocBaml 사용 팁

사용자 지정 컨트롤을 정의하는 모든 종속 어셈블리를 LocBaml의 로컬 디렉터리에 복사하거나 GAC에 설치해야 합니다. 이 작업은 지역화 API가 BAML(이진 XAML)을 읽을 때 종속 어셈블리에 액세스할 수 있어야 하기 때문에 필요합니다.
주 어셈블리가 서명된 경우 생성된 리소스 DLL도 서명되어야 로드됩니다.
지역화된 리소스 DLL 버전을 주 어셈블리와 동기화해야 합니다.