AEM Granite UI对话框内Heading组件text属性如何实现i18n国际化

核心结论 #

Granite UI Coral Foundation 系列组件本身原生支持对话框场景的文本i18n适配，只是它的i18n规则和内容页Sightly的实现逻辑完全不通用，之前配置不生效本质是混淆了两套渲染管线的适配方式，并不是这个组件不支持i18n。

方案1：原生标记法（适配AEM 6.5及以上版本） #

Granite UI 渲染引擎内置了i18n扫描逻辑，只需要在组件节点上显式标记需要做翻译的属性，引擎会自动从项目的i18n资源包匹配对应词条完成替换，不需要额外写自定义逻辑。
对应你的Heading组件配置，直接补充一行标记即可：

<disclaimer
    jcr:primaryType="nt:unstructured"
    sling:resourceType="granite/ui/components/coral/foundation/heading"
    level="3"
    text="Convert to i18n"
    xss:i18n=text/>

配置说明：

• xss:i18n=text 的作用是告诉渲染引擎：当前节点的text属性值需要走i18n翻译流程，引擎会自动拿原text的字符串作为词条key，匹配当前用户语言环境下的翻译值替换硬编码文本
• 翻译取值逻辑和内容页Sightly的i18n完全打通，会直接读取你已经维护的i18n JSON语言文件，不需要重复维护词条

方案2：全版本兼容写法（适配所有AEM版本） #

部分旧版本AEM的Foundation Heading组件，渲染时不会自动扫描同节点的xss:i18n标记，这时候可以直接用组件本身内置支持的i18n参数实现，从AEM 6.3到最新的云服务版本都能正常生效：

<disclaimer
    jcr:primaryType="nt:unstructured"
    sling:resourceType="granite/ui/components/coral/foundation/heading"
    level="3"
    text=""
    i18n="Convert to i18n"/>

配置说明：

• 组件渲染时会优先读取i18n属性的值作为翻译词条，通过Granite内置的i18n服务拿到对应语言的翻译结果，再把结果赋值给实际展示的heading文本
• 这种方式不需要依赖外层渲染引擎的扫描逻辑，不会因为版本差异出现适配问题

常见踩坑点说明 #

• 不要在对话框组件的属性里直接写Sightly语法，比如把text值写成${'Convert to i18n' @ i18n}，对话框的渲染走的是Granite专属的组件管线，不是内容页的HTL渲染链路，这类语法会被当成普通字符串渲染，不会被解析，这也是之前配置不生效的核心原因
• 确认你的i18n语言包路径是被Granite的i18n服务识别的：Granite对话框的i18n默认读取注册在框架i18n服务下的语言包，如果你的语言文件放在仅内容页读取的路径下，需要确保已经完成了语言包的注册，不然引擎读不到你维护的词条
• 不要尝试用自定义前端JS在页面加载后手动替换heading文本，这种方式会导致Coral组件的无障碍属性（比如aria标签）和实际展示文本不一致，不符合组件的可访问性规范

内容的提问来源于stack exchange，提问作者guradio