.. _lang:

====
lang
==== 

Tests the language of a node

Description
~~~~~~~~~~~
The fn:lang function tests the language of a node, which is determined by the 
existence of an xml:lang attribute on the node itself or among its ancestors. 
This function can be used on any node, not just one containing string values. It 
is often used in the predicates of path expressions to filter data for a 
particular language.

The $testLang argument specifies the language to test. The function returns true 
if the relevant xml:lang attribute of the $node has a value that matches the 
$testLang value. The function returns false if the relevant xml:lang attribute 
does not match $testlang, or if there is no relevant xml:lang attribute.

The relevant xml:lang attribute is the one that appears as an attribute of the 
context node itself, or of one of its ancestors. If more than one xml:lang 
attribute can be found among the node and its ancestors, the nearest one 
applies.

The matching process is case-insensitive. If $testLang is en, it matches the 
xml:lang value EN, and vice versa. Also, the value of the xml:lang attribute can 
be a sublanguage of the $testlang value. For example, en-US, en-UK, and en-US-UK 
are all sublanguages of en. Therefore, if $testlang is en, and xml:lang is 
en-US, the node will be matched. This does not work in reverse; if $testlang is 
en-US, and xml:lang is en, it will not match.

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - **Parameters**
     - **Description**
   * - testlang:string()
     - the language to test for
   * - node:node()
     - the node to test; otherwise uses the context node

Examples
~~~~~~~~
.. list-table::
   :widths: 50 50
   :header-rows: 1

   * - **XPath**
     - **Results**
   * - $in-xml//     desc[lang('en')]
     - <desc xml:lang="en-US">   <line>A line of text.</line> </desc>
   * - $in-xml//     desc[lang('en-US')]
     - <desc xml:lang="en-US">   <line>A line of text.</line> </desc>
   * - $in-xml//     desc[lang('fr')]
     - <desc xml:lang="fr">   <line>Une ligne de texte.</line> </desc>
   * - $in-xml//     desc/line[lang('en')]
     - <line>A line of text.</line>
   * - $in-xml[lang('en-US')]
     - ()
   * - $in-xml//     desc[lang('FR')]
     - <desc xml:lang="fr">   <line>Une ligne de texte.</line> </desc>