id="collation-managing-predefined-icu">
   <title>ICU Collations</title>

   <para>
    With ICU, it is not sensible to enumerate all possible locale names.  ICU
    uses a particular naming system for locales, but there are many more ways
    to name a locale than there are actually distinct locales.
    <command>initdb</command> uses the ICU APIs to extract a set of distinct
    locales to populate the initial set of collations.  Collations provided by
    ICU are created in the SQL environment with names in BCP 47 language tag
    format, with a <quote>private use</quote>
    extension <literal>-x-icu</literal> appended, to distinguish them from
    libc locales.
   </para>

   <para>
    Here are some example collations that might be created:

    <variablelist>
     <varlistentry id="collation-managing-predefined-icu-de-x-icu">
      <term><literal>de-x-icu</literal></term>
      <listitem>
       <para>German collation, default variant</para>
      </listitem>
     </varlistentry>

     <varlistentry id="collation-managing-predefined-icu-de-at-x-icu">
      <term><literal>de-AT-x-icu</literal></term>
      <listitem>
       <para>German collation for Austria, default variant</para>
       <para>
        (There are also, say, <literal>de-DE-x-icu</literal>
        or <literal>de-CH-x-icu</literal>, but as of this writing, they are
        equivalent to <literal>de-x-icu</literal>.)
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="collation-managing-predefined-icu-und-x-icu">
      <term><literal>und-x-icu</literal> (for <quote>undefined</quote>)</term>
      <listitem>
       <para>
        ICU <quote>root</quote> collation.  Use this to get a reasonable
        language-agnostic sort order.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    Some (less frequently used) encodings are not supported by ICU.  When the
    database encoding is one of these, ICU collation entries
    in <literal>pg_collation</literal> are ignored.  Attempting to use one
    will draw an error along the lines of <quote>collation "de-x-icu" for
    encoding "WIN874" does not exist</quote>.
   </para>
  </sect4>
  </sect3>

  <sect3 id="collation-create">
   <title>Creating New Collation Objects</title>

   <para>
    If the standard and predefined collations are not sufficient, users can
    create their own collation objects using the SQL
    command <xref linkend="sql-createcollation"/>.
   </para>

   <para>
    The standard and predefined collations are in the
    schema <literal>pg_catalog</literal>, like all predefined objects.
    User-defined collations should be created in user schemas.  This also
    ensures that they are saved by <command>pg_dump</command>.
   </para>

   <sect4 id="collation-managing-create-libc">
    <title>libc Collations</title>

    <para>
     New libc collations can be created like this:
<programlisting>
CREATE COLLATION german (provider = libc, locale = 'de_DE');
</programlisting>
     The exact values that are acceptable for the <literal>locale</literal>
     clause in this command depend on the operating system.  On Unix-like
     systems, the command <literal>locale -a</literal> will show a list.
    </para>

    <para>
     Since the predefined libc collations already include all collations
     defined in the operating system when the database instance is
     initialized, it is not often necessary to manually create new ones.
     Reasons might be if a different naming system is desired (in which case
     see also <xref linkend="collation-copy"/>) or if the operating system has
     been upgraded to provide new locale definitions (in which case see
     also <link linkend="functions-admin-collation"><function>pg_import_system_collations()</function></link>).
    </para>
   </sect4>

   <sect4 id="collation-managing-create-icu">
    <title>ICU Collations</title>

    <para>
     ICU collations can be created like:

<programlisting>