抠丁客 抠丁客
项目
编辑 (2025/12/24)

本地化

在探索本地化管道和本地化服务之前，您应该先了解本地化键。

本地化键的格式由两部分组成，即资源名称和键。 ResourceName::Key

如果您未指定资源名称，则 environment.ts 中声明的 defaultResourceName 将被视为默认资源。

const environment = {
  // ...
  localization: {
    defaultResourceName: "MyProjectName",
  },
};

因此，这两者将给出相同的结果：

<h1>{{ '::Key' | abpLocalization }}</h1>

<h1>{{ 'MyProjectName::Key' | abpLocalization }}</h1>

使用本地化管道

您可以使用 abpLocalization 管道来获取本地化文本，如以下示例所示：

<h1>{{ 'Resource::Key' | abpLocalization }}</h1>

此管道将用本地化文本替换键。

您还可以指定默认值，如下所示：

<h1>
  {{ { key: 'Resource::Key', defaultValue: 'Default Value' } |
  abpLocalization }}
</h1>

为了使用插值，您必须为管道提供参数，例如：

本地化数据以键值对形式存储：

{
  // ...
  AbpAccount: { // AbpAccount 是资源名称
    Key: "值",
    PagerInfo: "显示第 {0} 到 {1} 条，共 {2} 条记录"
  }
}

然后，我们可以像这样使用此键：

<h1>{{ 'AbpAccount::PagerInfo' | abpLocalization:'20':'30':'50' }}</h1>

<!-- 输出：显示第 20 到 30 条，共 50 条记录 -->

使用本地化服务

首先，您应该从 @abp/ng.core 导入 LocalizationService

import { LocalizationService } from '@abp/ng.core';
import { inject } from '@angular/core';

class MyClass {
  private localizationService = inject(LocalizationService);
}

之后，您就可以使用本地化服务了。

您可以将插值参数作为参数传递给 instant() 和 get() 方法。

this.localizationService.instant(
  "AbpIdentity::UserDeletionConfirmation",
  "John"
);

// 使用回退值
this.localizationService.instant(
  {
    key: "AbpIdentity::UserDeletionConfirmation",
    defaultValue: "默认值",
  },
  "John"
);

// 输出
// 用户 'John' 将被删除。您确认吗？

要获取作为 Observable 的本地化文本，请使用 get 方法而不是 instant：

this.localizationService.get("Resource::Key");

// 使用回退值
this.localizationService.get({
  key: "Resource::Key",
  defaultValue: "默认值",
});

UI 本地化

本地化可以在后端确定。因此，Angular UI 从 application-localization API 的响应中获取本地化资源，然后将这些资源与 ConfigStateService 中的 configuration state 合并。您也可以在 UI 端确定本地化。

参见示例：

import { provideAbpCore, withOptions } from "@abp/ng.core";

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideAbpCore(
      withOptions({
        // ...,
        localizations: [
          {
            culture: "en",
            resources: [
              {
                resourceName: "MyProjectName",
                texts: {
                  Administration: "Administration",
                  HomePage: "Home",
                },
              },
            ],
          },
          {
            culture: "de",
            resources: [
              {
                resourceName: "MyProjectName",
                texts: {
                  Administration: "Verwaltung",
                  HomePage: "Startseite",
                },
              },
            ],
          },
        ],
      })
    ),
  ],
};

您也可以在特性提供程序配置中声明本地化：

// 您的特性配置

export function provideFeatureConfiguration(): EnvironmentProviders {
  return provideAbpCoreChild({
    localizations: [
      {
        culture: "en",
        resources: [
          {
            resourceName: "MyProjectName",
            texts: {
              Administration: "Administration",
              HomePage: "Home",
            },
          },
        ],
      },
      {
        culture: "de-DE",
        resources: [
          {
            resourceName: "MyProjectName",
            texts: {
              Administration: "Verwaltung",
              HomePage: "Startseite",
            },
          },
        ],
      },
    ],
  });
}

上面的本地化可以像这样使用：

<div>{{ 'MyProjectName::Administration' | abpLocalization }}</div>

<div>{{ 'MyProjectName::HomePage' | abpLocalization }}</div>

注意： 如果您在 UI 和后端指定了相同的本地化，则后端的本地化将覆盖 UI 的本地化。

RTL 支持

从 v2.9 版本开始，ABP 支持 RTL。如果您使用 v2.9 或更高版本生成新项目，则一切已设置好，无需进行任何更改。如果您要将项目从较早版本迁移，请遵循以下 2 个步骤：

步骤 1. 为 Bootstrap LTR 和 RTL 创建块

在 angular.json 中找到 样式配置，并确保您的项目中包含 bootstrap-rtl.min 和 bootstrap-ltr.min 块，如下所示。

{
  "projects": {
    "MyProjectName": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              {
                "input": "node_modules/@fortawesome/fontawesome-free/css/all.min.css",
                "inject": true,
                "bundleName": "fontawesome-all.min"
              },
              {
                "input": "node_modules/@fortawesome/fontawesome-free/css/v4-shims.min.css",
                "inject": true,
                "bundleName": "fontawesome-v4-shims.min"
              },
              {
                "input": "node_modules/@abp/ng.theme.shared/styles/bootstrap-rtl.min.css",
                "inject": false,
                "bundleName": "bootstrap-rtl.min"
              },
              {
                "input": "node_modules/bootstrap/dist/css/bootstrap.min.css",
                "inject": true,
                "bundleName": "bootstrap-ltr.min"
              },
              "apps/dev-app/src/styles.scss"
            ]
          }
        }
      }
    }
  }
}

步骤 2. 清除 AppComponent 中延迟加载的 Fontawesome

如果您如上所示创建并注入了 Fontawesome 块，则不再需要 v2.9 之前版本实现的 AppComponent 中的延迟加载。只需将其移除。新版本模板中的 AppComponent 如下所示：

import { Component } from "@angular/core";

@Component({
  selector: "app-root",
  template: `
    <abp-loader-bar />
    <router-outlet />
  `,
})
export class AppComponent {}

注册新区域设置

由于 ABP 支持多种语言，Angular 区域设置文件使用 Webpack 的 import 函数 延迟加载，以避免增加包大小，并使用 registerLocaleData 函数注册 Angular 核心。要包含在包中的块由 Webpack 的魔法注释 硬编码指定。因此，必须将一个返回 Webpack import 函数的 registerLocale 函数传递给 provideAbpCore(withOptions({...}))。

registerLocaleFn

从 @abp/ng.core/locale 包导出的 registerLocale 函数是一个高阶函数。

它接受以下参数：

  • cultureNameLocaleFileMap - 一个将文化名称映射到其相应区域设置文件的对象。
  • errorHandlerFn - 一个处理区域设置加载期间发生的任何错误的函数。

它返回一个 Webpack import 函数。

您应该在 provideAbpCore 的 withOptions 函数中使用 registerLocale，如下例所示：

import { provideAbpCore, withOptions } from "@abp/ng.core";
import { registerLocale } from "@abp/ng.core/locale";

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideAbpCore(
      withOptions({
        // ...,
        registerLocaleFn: registerLocale(
          // 您可以可选地传递 cultureNameLocaleFileMap 和 errorHandlerFn
          {
            cultureNameLocaleFileMap: { "pt-BR": "pt" },
            errorHandlerFn: ({ resolve, reject, locale, error }) => {
              // 可以在此处理错误
            },
          }
        ),
      })
    ),
    // ...
  ],
};

文化名称到 Angular 区域设置文件名的映射

.NET 中定义的一些文化名称与 Angular 区域设置不匹配。在这种情况下，Angular 应用程序在运行时会抛出如下错误：

locale-error

如果您看到类似错误，应像下面这样将 cultureNameLocaleFileMap 属性传递给 registerLocale 函数。

// app.config.ts

import { registerLocale } from "@abp/ng.core/locale";
// 如果您拥有商业许可证和语言管理模块，请添加以下导入
// import { registerLocale } from '@volo/abp.ng.language-management/locale';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideAbpCore(
      withOptions({
        // ...,
        registerLocaleFn: registerLocale({
          cultureNameLocaleFileMap: {
            DotnetCultureName: "AngularLocaleFileName",
            "pt-BR": "pt", // 示例
          },
        }),
      })
    ),
  ],
};

查看 Angular 中的所有区域设置文件。

添加新文化

如果您想注册一种新语言，可以将以下代码添加到 app.config.ts 中，并用正确的区域设置名称替换 your-locale 占位符。

//app.config.ts

import { storeLocaleData } from "@abp/ng.core/locale";
import(
  /* webpackChunkName: "_locale-your-locale-js"*/
  /* webpackMode: "eager" */
  "@angular/common/locales/your-locale.js"
).then((m) => storeLocaleData(m.default, "your-locale"));

您还可以配置一个自定义的 registerLocale 函数，该函数可以传递给 abp 核心提供程序配置选项：

// register-locale.ts

import { differentLocales } from "@abp/ng.core";
export function registerLocale(locale: string) {
  return import(
    /* webpackChunkName: "_locale-[request]"*/
    /* webpackInclude: /[/\\](en|fr).js/ */
    /* webpackExclude: /[/\\]global|extra/ */
    `@angular/common/locales/${differentLocales[locale] || locale}.js`
  );
}

// app.config.ts

import { registerLocale } from "./register-locale";

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideAbpCore(
      withOptions({
        // ...,
        registerLocaleFn: registerLocale,
      })
    ),
    //...
  ],
};

添加自定义 registerLocale 函数后，只有 en 和 fr 区域设置文件将作为单独的块创建。 这是因为只有这些区域设置包含在 webpackInclude 配置中。

locale chunks

您添加到 webpackInclude 魔法注释的区域设置文件将被包含在包中。

另请参阅

在本文档中