WordPress函数：language_attributes 输出语言属性

language_attributes() 是 WordPress 用来在网页的 <html> 标签中输出语言和文本方向（如 lang="zh-CN" dir="ltr"）的核心函数，它确保你的网站能正确告诉浏览器和搜索引擎页面所使用的语言，是构建国际化网站和提升可访问性的基础。

语法

language_attributes( string $doctype = 'html' );

参数：$doctype（可选），一个字符串，指定文档类型。默认为 html。虽然理论上可以设置为其他如xhtml，但在现代WordPress主题中，永远只应使用默认值。
返回值：无。此函数直接输出（echo）编译好的属性和值。
函数位置：/wp-includes/general-template.php

实际用法

基础场景

在主题的 header.php 文件中，用于 <html> 标签的开头部分。这是它最核心、最常见的用法。

<!DOCTYPE html>
<!-- ✅ 正确做法：在 <html> 标签中直接调用 -->
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <?php wp_head(); ?>
</head>

它会根据你的站点设置（设置 > 常规 > 站点语言）输出类似这样的结果：lang="zh-CN" dir="ltr"。

进阶场景

在多语言网站中（例如使用 WPML 或 Polylang 插件），language_attributes() 会自动识别当前正在显示的语言并输出对应的属性。这是因为它使用了 get_bloginfo('language') 作为过滤器，而多语言插件会动态修改这个值。

<!-- 当用户访问英文页面时，可能输出： -->
<html lang="en-US" dir="ltr">
<!-- 当用户访问阿拉伯语页面时，可能输出： -->
<html lang="ar" dir="rtl">

你不需要在模板中写任何条件判断逻辑，函数和插件会为你处理好一切。

特殊场景

在极少数情况下，你可能需要通过钩子来修改输出的属性。例如，为一个特定页面模板强制指定某种语言。

// 在主题的 functions.php 文件中添加过滤器
add_filter( 'language_attributes', 'my_custom_lang_attr' );
function my_custom_lang_attr( $output ) {
    // 如果当前页面使用特定模板，则修改语言属性
    if ( is_page_template( ‘template-chinese-classical.php’ ) ) {
        // 将输出替换为文言文的语言代码
        return 'lang="lzh" dir="ltr"';
    }
    return $output; // 其他情况返回默认值
}

易错点分析

❌ 错误1：忘记在 header.php 中调用此函数。
这会导致HTML标签缺少关键的语言声明，不利于SEO和屏幕阅读器等辅助技术识别。

<!-- ❌ 错误：<html> 标签是空的 -->
<html>
<head>...</head>

✅ 正确做法：务必在 header.php 的 <html> 标签内调用它。

<!-- ✅ 正确：包含完整的语言属性 -->
<html <?php language_attributes(); ?>>
<head>...</head>

❌ 错误2：在循环内、页脚或其他地方错误地调用它。
language_attributes() 的设计目的就是用于 <html> 标签，每个页面有且仅有一个。在其他地方调用毫无意义，并且可能导致代码混乱。

<!-- ❌ 错误：在文章循环中调用 -->
<?php while ( have_posts() ) : the_post(); ?>
    <article>
        <html <?php language_attributes(); ?>> <!-- 这里完全错误！ -->
        <h1><?php the_title(); ?></h1>

✅ 正确做法：仅在 header.php 文件的 <html> 标签内调用一次。
逻辑清晰，符合HTML规范。

最佳实践

性能与兼容性

这个函数本身极其轻量，几乎不产生性能开销。最佳实践的核心是不要干扰它。
– 避免覆盖默认值：除非你正在开发一个高度定制化的多语言系统，否则永远使用默认参数 language_attributes()，不要传入任何值。传入xhtml等已过时的文档类型可能会引发兼容性问题。
– 依赖缓存：对于多语言站点，输出内容由插件动态决定。请确保使用像 WP Rocket 或 W3 Total Cache 这样的缓存插件，并为不同语言的页面设置单独的缓存规则，以保持最佳性能。

代码可维护性

保持其用法的纯粹性和标准化。
– 位置固定：始终将它放在 header.php 中 <!DOCTYPE html> 之后的 <html> 标签内。这形成了所有WordPress主题的标准入口结构，让其他开发者一目了然。
– 与 body_class() 协同：将 language_attributes()（用于<html>标签）和 body_class()（用于<body>标签）视为一对“页面属性标识符”。它们共同为CSS和JavaScript提供了强大的上下文钩子。

<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>...</head>
<body <?php body_class(); ?>>

实际项目应用

为子主题做准备：在创建父主题时，正确使用 language_attributes() 意味着子主题开发者无需关心语言设置问题，他们可以直接复用或覆盖 header.php，而基础的多语言支持依然有效。
RTL（从右到左）样式支持：该函数输出的 dir="rtl" 属性是WordPress自动加载RTL样式表 (*-rtl.css) 的关键依据。正确使用它，就能免费获得对希伯来语、阿拉伯语等语言的排版支持。
结构化数据与SEO：清晰的语言声明 (lang属性) 是搜索引擎理解页面内容的基础，也有利于屏幕阅读器以正确的语音和语调朗读内容。正确调用此函数，是网页可访问性的最基本、也是最重要的一步。