/*
 * Copyright (c) 2009, 2010 and 2011 Frank G. Bennett, Jr. All Rights
 * Reserved.
 *
 * The contents of this file are subject to the Common Public
 * Attribution License Version 1.0 (the “License”); you may not use
 * this file except in compliance with the License. You may obtain a
 * copy of the License at:
 *
 * http://bitbucket.org/fbennett/citeproc-js/src/tip/LICENSE.
 *
 * The License is based on the Mozilla Public License Version 1.1 but
 * Sections 14 and 15 have been added to cover use of software over a
 * computer network and provide for limited attribution for the
 * Original Developer. In addition, Exhibit A has been modified to be
 * consistent with Exhibit B.
 *
 * Software distributed under the License is distributed on an “AS IS”
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is the citation formatting software known as
 * "citeproc-js" (an implementation of the Citation Style Language
 * [CSL]), including the original test fixtures and software located
 * under the ./std subdirectory of the distribution archive.
 *
 * The Original Developer is not the Initial Developer and is
 * __________. If left blank, the Original Developer is the Initial
 * Developer.
 *
 * The Initial Developer of the Original Code is Frank G. Bennett,
 * Jr. All portions of the code written by Frank G. Bennett, Jr. are
 * Copyright (c) 2009 and 2010 Frank G. Bennett, Jr. All Rights Reserved.
 *
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU Affero General Public License (the [AGPLv3]
 * License), in which case the provisions of [AGPLv3] License are
 * applicable instead of those above. If you wish to allow use of your
 * version of this file only under the terms of the [AGPLv3] License
 * and not to allow others to use your version of this file under the
 * CPAL, indicate your decision by deleting the provisions above and
 * replace them with the notice and other provisions required by the
 * [AGPLv3] License. If you do not delete the provisions above, a
 * recipient may use your version of this file under either the CPAL
 * or the [AGPLv3] License.”
 */

@1385

``language``
    Tests whether the ``language`` field of the item to be
    rendered matches any of the given locales.  This is 
    treated as a single test for all values of purposes of
    the ``match`` attribute ("none", "any", or "all").
    When the test succeeds, the locale is changed to the
    tested value for all child nodes called via the test.
    See `The language test attribute`_ below for details
    on the locale selection.


@1398

The language test attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ``language`` test attribute accepts a list of locale
specifiers.  Specifiers may be either a two-character
language code (e.g. "en", for English), or a two-character language code
and a two-character region code separated by a hyphen
(e.g. "de-CH", or the variant of German spoken in Switzerland).
Testing and locale assignment are performed as follows:

1. The test succeeds if any of the given language specifiers match
   against the ``language`` field of the item to be rendered;

2. Two-character language specifiers (those without a region code)
   match any item ``language`` value for that language, regardless
   of the region tag;

3. The first language specifier in the list determines the
   locale to be set on children of the condition statement.

The following examples illustrate this behavior:

.. sourcecode:: xml

    <choose>
      <if language="pt">
        <text macro="cite"/>
      </if>
      <else>
        <text macro="cite"/>
      </else>
    </choose>

In the example above, the "cite" macro will be executed with the
base locale of Portuguese ("pt-PT") for any item with a ``language`` 
field value of Portuguese (e.g. "pt", "pt-BR", or "pt-PT").  For
all other items, the "cite" macro will be executed with the default
locale of the style.

.. sourcecode:: xml

    <choose>
      <if language="zh-CH">
        <text macro="cite"/>
      </if>
      <else-if language="zh-TW">
        <text macro="cite"/>
      </else-if>
      <else>
        <text macro="cite"/>
      </else>
    </choose>

In the example above, the "cite" macro will be executed with
the mainland (simplified) Chinese locale for items that have the
specifier "zh-CH" set in the ``language`` field.  Items
that have the specifier for the non-simplified version of
Chinese used in Taiwan set in the ``language`` field ("zh-TW") will be
rendered with that locale.  All other items will be rendered with
the default locale of the style.


.. sourcecode:: xml

    <choose>
      <if language="de-AT de">
        <text macro="cite"/>
      </if>
      <else>
        <text macro="cite"/>
      </else>
    </choose>


In the example above, the "cite" macro will be executed
with the Austrian locale ("de-AT") for all items that have
German set in the item ``language`` field, regardless of
region code.