¿Cuándo debería usarse add_rewrite_tag()?

La diferencia fundamental es:

• El add_rewrite_rule() añade una regla particular que es interpretada
• El add_rewrite_tag() añade un marcador de posición para usar en estructuras de URL. Este marcador luego se usa para generar múltiples reglas.

Por ejemplo - supongamos que eres una agencia de viajes anunciando hoteles en varios países. Puedes querer que la URL de un hotel sea como:

  www.ejemplo.com/hoteles/ReinoUnido/Balmoral

Donde el país (ReinoUnido en este ejemplo) es un término de taxonomía personalizada y Balmoral es un hotel (tipo de contenido). Podríamos añadir reglas de reescritura para esto, pero entonces tendríamos que generar una regla para:

• el hotel en sí
• los archivos adjuntos del hotel
• Una regla para hoteles (publicaciones) que abarquen varias páginas, etc.

Generar estas reglas puede volverse complicado. Además, probablemente estaremos compitiendo con las propias reglas de WordPress para ese tipo de contenido - generadas a partir de la estructura de enlaces permanentes que establecemos al registrar el tipo de contenido. (En cualquier caso, deja que WordPress haga el trabajo).

Esta 'estructura de enlaces permanentes' - similar a lo que configuras para publicaciones en los ajustes de enlaces permanentes - determina las reglas de reescritura que genera WordPress. Pero como queremos una estructura que contenga algo desconocido (el país) - que queremos que sea interpretado - necesitamos proporcionar un marcador de posición en la forma %pais%. (Es casi idéntico a %categoria% para publicaciones).

Por ejemplo:

add_action_init('init','wpse71305_registrar_tipos');

function wpse71305_registrar_tipos(){

     //También necesitarás registrar la taxonomía de país aquí.

     //Añadir etiqueta 'pais'.
     add_rewrite_tag('%pais%', '([^&/]+)'));

     //Registrar tipo de contenido hotel con etiqueta %pais%
    $args = array(  
        ...
        'has_archive'=>true,  
        'rewrite' => array(  
            'slug'=>'hoteles/%pais%',  
            'with_front'=> false,  
            'feed'=> true,  
            'pages'=> true  
        )  
        ...
    );  
    register_post_type('hotel',$args);  
}

Nota: WordPress no sabe cómo generar la URL a partir de la etiqueta %pais% - necesitas indicarle cómo hacerlo. (Cubro esto en un artículo que he enlazado abajo).

Finalmente WordPress también almacenará el valor coincidente para que puedas recuperarlo via get_query_var() (algo que no ocurre con una regla de reescritura estándar).

También puedes crear etiquetas para usar en la estructura de enlaces permanentes de publicaciones (configurarla en la página de Ajustes de Enlaces Permanentes).

Al añadir una etiqueta, podemos usarla en estructuras de enlaces permanentes. WordPress entonces sabe:

• Qué esperar
• Cómo interpretar la URL (verificar que coincide)
• Cómo interpretar el valor (ej. 'ReinoUnido')

(Como referencia, ver este artículo que escribí: http://wp.tutsplus.com/tutorials/creative-coding/the-rewrite-api-the-basics/).

Edición

Como se menciona en los comentarios, el ejemplo anterior no es ideal ya que register_taxonomy() de hecho llama a add_rewrite_tag().

Respecto a la documentación del Codex sobre usarlos 'en combinación': esto puede ser engañoso ya que ambos pueden usarse independientemente. Como se mencionó anteriormente, sin embargo, add_rewrite_tag() añade el nombre de la etiqueta a las 'variables de consulta' que WordPress entiende. En la práctica esto te permite recuperar el valor con get_query_var(). Así, cuando add_rewrite_rule() se usa con add_rewrite_tag(), la variable será almacenada por WordPress. Pero hay otras formas de hacer esto (ver esta respuesta - nota también el comentario de Rob Vermeer).

También relacionado: ¿Cómo recuperar variables $_GET de URLs reescritas?