Una intranet multilingüe en SharePoint requiere algo más que contenido de páginas traducido. Para que los filtros de búsqueda, los metadatos basados en taxonomía y las columnas de metadatos administrados se muestren correctamente en cada idioma, los propios términos necesitan etiquetas traducidas en el almacén de términos de SharePoint. Este artículo explica cómo provisionar una taxonomía multilingüe mediante programación con PnP PowerShell, incluyendo los problemas de parámetros que encontrarás y cómo solucionarlos.
Este artículo acompaña al script Create Multilingual Term Store de la página de scripts.
Por Qué Importa el Aprovisionamiento Automático de Taxonomía
Si estás construyendo una intranet multilingüe — especialmente una que utiliza PnP Modern Search con filtros basados en taxonomía — necesitas que tu almacén de términos contenga etiquetas traducidas para cada término. Sin ellas, las etiquetas de los filtros y los metadatos de los resultados de búsqueda se muestran en el idioma predeterminado independientemente de la preferencia de idioma del usuario.
Hacer esto manualmente a través de la interfaz del almacén de términos de SharePoint es viable para taxonomías pequeñas. Para cualquier cosa más allá de un puñado de términos en varios conjuntos de términos e idiomas, la entrada manual se vuelve propensa a errores, lenta e imposible de reproducir de forma consistente entre entornos. Un enfoque mediante scripts controlado por un archivo de configuración JSON te proporciona repetibilidad, trazabilidad y la capacidad de desplegar la misma taxonomía en dev, test y producción con un único comando.
Qué Hace el Script
El script aprovisiona tres capas de estructura de taxonomía:
- Grupo de términos — el contenedor de nivel superior, equivalente a un departamento o espacio de nombres de proyecto en el almacén de términos
- Conjuntos de términos — agrupaciones lógicas de términos relacionados dentro de un grupo (Departamentos, Tipos de Documento, Ubicaciones, etc.)
- Términos — los valores individuales de la taxonomía, cada uno con una etiqueta en inglés por defecto y etiquetas traducidas opcionales por idioma
Todo está controlado por un archivo de configuración JSON. El nombre y la descripción del grupo de términos se encuentran en el nivel superior del JSON, lo que significa que el mismo script puede aprovisionar taxonomías completamente distintas cambiando el JSON — útil cuando se gestionan varios entornos o despliegues de clientes.
El script comprueba si ya existen grupos de términos, conjuntos de términos y términos antes de intentar crearlos, y omite cualquier cosa que ya exista. Volver a ejecutarlo sobre una taxonomía parcialmente aprovisionada retoma donde lo dejó sin duplicar contenido.
Todas las operaciones se registran en un archivo CSV con marca de tiempo junto con la salida de consola, lo que proporciona un registro de auditoría completo de cada acción realizada.
Los Problemas de PnP PowerShell
Aquí es donde falla la mayor parte de la documentación. Aplicar traducciones con PnP PowerShell no es tan sencillo como debería, y los problemas varían según la versión del módulo.
El Parámetro -Label No Existe en PnP.PowerShell 3.x
El primer instinto al aplicar una etiqueta traducida a un término es usar algo como:
Set-PnPTerm -Identity $term.Id -Label "Ressources Humaines" -Lcid 1036En PnP.PowerShell 3.x, -Label no es un parámetro válido. Al ejecutarlo se produce el error:
A parameter cannot be found that matches parameter name 'Label'.Puedes verificar qué parámetros están disponibles en tu versión con:
(Get-Command Set-PnPTerm).Parameters.KeysEn la versión 3.x el parámetro correcto es -Name combinado con -Lcid. Esto establece el nombre de visualización del término para el idioma especificado:
Set-PnPTerm `
-Identity $term.Id `
-TermSet "Departments" `
-TermGroup "Intranet_Taxonomy" `
-Name "Ressources Humaines" `
-Lcid 1036Problemas de Temporización en el Almacén de Términos
La API del almacén de términos de SharePoint es asíncrona de maneras que no siempre son evidentes. Dos problemas de temporización causaron fallos consistentes durante el desarrollo.
Los nuevos grupos de términos necesitan tiempo para aprovisionarse. Después de que New-PnPTermGroup devuelva correctamente, el grupo no está disponible inmediatamente para Get-PnPTermGroup. Intentar obtenerlo demasiado rápido provoca un error de índice. La solución es un bucle de reintento que vuelve a obtener el grupo con un retraso entre intentos en lugar de una espera fija:
$retries = 0
$termGroup = $null
while (-not $termGroup -and $retries -lt 5) {
Start-Sleep -Seconds 10
try {
$termGroup = Get-PnPTermGroup -Identity $TermGroupName -ErrorAction Stop
}
catch {
$retries++
Write-Host "Waiting for term group to provision... attempt $retries" -ForegroundColor Yellow
}
}Los nuevos términos necesitan tiempo antes de que se puedan aplicar etiquetas. Después de que New-PnPTerm cree un término, llamar a Set-PnPTerm inmediatamente para aplicar una traducción devuelve "The specified term does not exist" — aunque el término acaba de crearse correctamente. La solución es volver a obtener el término después de crearlo con una breve espera, en lugar de usar el objeto devuelto por New-PnPTerm:
$null = New-PnPTerm -TermSet $termSetName -TermGroup $TermGroupName -Name $termName -Lcid 1033
Start-Sleep -Seconds 3
$targetTerm = Get-PnPTerm -TermSet $termSetName -TermGroup $TermGroupName -Identity $termNameEl objeto recuperado tiene una propiedad Id completamente hidratada que Set-PnPTerm -Identity puede utilizar de forma fiable.
Conflictos de Guardado al Escribir Traducciones
Escribir múltiples etiquetas traducidas en rápida sucesión puede provocar conflictos de guardado en el almacén de términos:
TermStoreErrorCodeEx:Term update failed because of save conflict.Una espera de dos segundos entre cada escritura de etiqueta resuelve esto de forma fiable para taxonomías de tamaño habitual.
La Configuración JSON
El archivo JSON controla toda la ejecución del aprovisionamiento. La estructura es sencilla:
{
"TermGroupName": "Intranet_Taxonomy",
"TermGroupDescription": "Terms used for the Intranet Taxonomy",
"TermGroups": [
{
"TermSet": "Departments",
"Terms": [
{
"Name": "Human Resources",
"Translations": {
"1036": "Ressources Humaines",
"3082": "Recursos Humanos"
}
},
{
"Name": "Finance",
"Translations": {
"1036": "Finance"
}
}
]
}
]
}Aspectos importantes del esquema:
TermGroupName en el JSON tiene precedencia sobre la variable del script. Si TermGroupName no está en el JSON, el script recurre a la variable definida al inicio del archivo del script. Si ninguno está definido, el script genera un error claro antes de intentar ningún aprovisionamiento.
Los términos admiten tanto cadenas simples como objetos. Si un término no necesita traducciones, puedes incluirlo como una cadena simple en lugar de un objeto:
"Terms": [
"Finance",
{
"Name": "Human Resources",
"Translations": { "1036": "Ressources Humaines" }
}
]Esto mantiene el JSON limpio para taxonomías en las que solo algunos términos necesitan traducción.
Los códigos LCID se corresponden con idiomas específicos. Los más comunes en despliegues europeos:
| LCID | Idioma |
|---|---|
| 1033 | Inglés (predeterminado) |
| 1036 | Francés |
| 3082 | Español (España) |
| 1031 | Alemán |
| 1040 | Italiano |
| 1043 | Neerlandés |
Requisitos Previos
Antes de ejecutar el script:
Los idiomas de destino deben estar habilitados en el almacén de términos. En el Centro de Administración de SharePoint → Más características → Almacén de términos → Configuración de idioma, añade cada idioma que vayas a utilizar. Si el idioma no está habilitado a nivel del almacén de términos, las escrituras de etiquetas para ese LCID fallarán silenciosamente o generarán errores.
Permisos de Administrador de SharePoint o Administrador del Almacén de Términos. Los permisos estándar de propietario de sitio no son suficientes para operaciones de escritura en el almacén de términos a nivel de inquilino.
Ejecutar el Script
El script solicita la ruta del archivo JSON en tiempo de ejecución. Verás la salida en consola de cada operación y un archivo de registro CSV escrito en el mismo directorio que el script.
Una ejecución correcta tiene este aspecto:
Connecting to SharePoint...
Connected successfully
Using TermGroupName from JSON: 'Intranet_Taxonomy'
Checking term group 'Intranet_Taxonomy'...
Found existing term group 'Intranet_Taxonomy'
Processing term set: 'Departments'
Found existing term set: 'Departments'
Processing term: 'Human Resources'
Term already exists: 'Human Resources'
Added label 'Ressources Humaines' (LCID 1036) to 'Human Resources'Verificar los Resultados
Una vez completado el script, verifica las traducciones en el Centro de Administración de SharePoint → Más características → Almacén de términos. Navega a tu grupo de términos → conjunto de términos → selecciona un término → la pestaña General muestra la tabla de Traducciones y sinónimos con cada idioma y su etiqueta.
Deberías ver tu etiqueta en inglés predeterminada y cada etiqueta traducida junto a la fila de idioma correspondiente.
Usar la Taxonomía en PnP Modern Search
Aprovisionar la taxonomía es el primer paso. Antes de que PnP Modern Search pueda usar etiquetas traducidas para la visualización de filtros, se requieren varios pasos más:
- Crear una columna de sitio de tipo Metadatos administrados y vincularla al conjunto de términos
- Aplicar la columna de sitio al tipo de contenido o biblioteca de documentos relevante
- Etiquetar contenido — las páginas o elementos deben tener términos aplicados a la columna
- Esperar un rastreo — una vez que el rastreador visita el sitio e indexa el contenido etiquetado, crea automáticamente una propiedad rastreada llamada
ows_taxId_TuColumna(donde TuColumna coincide con el nombre interno de tu columna de sitio) - Mapear la propiedad rastreada — en el Centro de Administración de SharePoint → Búsqueda → Administrar esquema de búsqueda, mapea
ows_taxId_TuColumnaa una propiedad administrada RefinableString limpia sin otros mapeos - Activar una reindexación — para que el mapeo se aplique al contenido ya indexado
- Configurar PnP Modern Search — establece el RefinableString como el slot Tags en la fuente de datos con la localización habilitada, y usa la referencia
{{slot item @root.slots.Tags}}correspondiente en tu plantilla de tarjeta
La propiedad rastreada ows_taxId_ es la que contiene el GUID del término y la información de etiqueta por idioma que necesita PnP Modern Search para mostrar filtros multilingües. La propiedad rastreada ows_TuColumna solo contiene la etiqueta predeterminada y debe mapearse a un RefinableString separado si se necesita para la visualización no localizada.
La configuración completa para PnP Modern Search multilingüe — mapeo de propiedades administradas, plantillas de tarjeta de tipo de resultado y localización de filtros — se trata en la serie multilingüe de PnP Modern Search en las páginas técnicas.