about_Script_Internationalization

Artículo
04/13/2023

Descripción breve

Describe las características de internacionalización de scripts que facilitan que los scripts muestren mensajes e instrucciones a los usuarios en su lenguaje de interfaz de usuario (UI).

Descripción larga

Las características de internacionalización de scripts de PowerShell le permiten servir mejor a los usuarios en todo el mundo mostrando mensajes de ayuda y usuario en el idioma del usuario.

Las características de internacionalización de scripts consultan la referencia cultural de la interfaz de usuario del sistema operativo durante la ejecución, importan las cadenas de texto traducidas adecuadas y las muestran al usuario. La sección Datos permite almacenar cadenas de texto independientes del código para que se identifiquen y extraigan fácilmente. Un nuevo cmdlet, ConvertFrom-StringData, convierte cadenas de texto en tablas hash similares al diccionario para facilitar la traducción.

Para admitir el texto de ayuda internacional, PowerShell incluye las siguientes características:

Sección Datos que separa las cadenas de texto de las instrucciones de código. Para obtener más información sobre la sección Datos, consulte about_Data_Sections.
Nuevas variables automáticas $PSCulture y $PSUICulture. $PSCulture almacena el nombre del idioma de la interfaz de usuario usado en el sistema para elementos como la fecha, la hora y la moneda. La $PSUICulture variable almacena el nombre del idioma de la interfaz de usuario usado en el sistema para elementos de la interfaz de usuario, como menús y cadenas de texto.
Un cmdlet, ConvertFrom-StringData, que convierte cadenas de texto en tablas hash similares al diccionario para facilitar la traducción. Para obtener más información, vea ConvertFrom-StringData.
Nuevo tipo de archivo, .psd1, que almacena cadenas de texto traducidas. Los .psd1 archivos se almacenan en subdirectorios específicos del lenguaje del directorio de scripts.
Cmdlet, Import-LocalizedData, que importa cadenas de texto traducidas para un idioma especificado en un script en tiempo de ejecución. Este cmdlet reconoce e importa cadenas en cualquier idioma compatible con Windows. Para obtener más información, vea Import-LocalizedData.

Sección de datos: Almacenamiento de cadenas predeterminadas

Use una sección Datos en el script para almacenar las cadenas de texto en el idioma predeterminado. Organice las cadenas en pares clave-valor en una cadena aquí. Cada par clave-valor debe estar en una línea independiente. Si incluye comentarios, los comentarios deben estar en líneas independientes.

El ConvertFrom-StringData cmdlet convierte los pares clave-valor de la cadena aquí en una tabla hash similar al diccionario que se almacena en el valor de la variable de sección Data.

En el ejemplo siguiente, la sección Datos del World.ps1 script incluye el conjunto inglés-Estados Unidos (en-US) de mensajes de solicitud de un script. El ConvertFrom-StringData cmdlet convierte las cadenas en una tabla hash y las almacena en la $msgtable variable .

$msgTable = Data {
    #culture="en-US"
    ConvertFrom-StringData @'
    helloWorld = Hello, World.
    errorMsg1 = You cannot leave the user name field blank.
    promptMsg = Please enter your user name.
'@
}

Para obtener más información sobre las cadenas aquí, consulte about_Quoting_Rules.

Archivos PSD1: Almacenar cadenas traducidas

Guarde los mensajes de script para cada idioma de la interfaz de usuario en archivos de texto independientes con el mismo nombre que el script y la extensión de nombre de .psd1 archivo. Almacene los archivos en subdirectorios del directorio de script con nombres de referencias culturales en el formato siguiente:

<language>-<region>

Ejemplos: de-DE, ar-SA y zh-Hans

Por ejemplo, si el World.ps1 script se almacena en el C:\Scripts directorio, creará una estructura de directorios de archivos similar a la siguiente:

C:\Scripts
C:\Scripts\World.ps1
C:\Scripts\de-DE\World.psd1
C:\Scripts\ar-SA\World.psd1
C:\Scripts\zh-CN\World.psd1
...

El World.psd1 archivo del subdirectorio de de-DE del directorio de script puede incluir la siguiente instrucción:

ConvertFrom-StringData -StringData @'
helloWorld = Hallo, Welt.
errorMsg1 = Das Feld Benutzername darf nicht leer sein.
promptMsg = Geben Sie Ihren Benutzernamen ein.
'@

Del mismo modo, el World.psd1 archivo en el subdirectorio ar-SA del directorio de script podría incluir la siguiente instrucción:

ConvertFrom-StringData -StringData @'
helloWorld = مرحبًا أيها العالَم
errorMsg1 = لا يمكنك ترك حقل اسم المستخدم فارغًا
promptMsg = يرجى إدخال اسم المستخدم الخاص بك
'@

Import-LocalizedData: recuperación dinámica de cadenas traducidas

Para recuperar las cadenas en el idioma de la interfaz de usuario del usuario actual, use el Import-LocalizedData cmdlet .

Import-LocalizedData busca el valor de la $PSUICulture variable automática e importa el contenido de los <script-name>.psd1 archivos en el subdirectorio que coincide con el $PSUICulture valor. A continuación, guarda el contenido importado en la variable especificada por el valor del parámetro BindingVariable .

Import-LocalizedData -BindingVariable msgTable

Por ejemplo, si el Import-LocalizedData comando aparece en el C:\Scripts\World.ps1 script y el valor de $PSUICulture es "ar-SA", Import-LocalizedData busca el siguiente archivo:

C:\Scripts\ar-SA\World.psd1

A continuación, importa las cadenas de texto árabe del archivo en la $msgTable variable, reemplazando las cadenas predeterminadas que se pueden definir en la sección Datos del World.ps1 script.

Como resultado, cuando el script usa la variable para mostrar mensajes $msgTable de usuario, los mensajes se muestran en árabe.

Por ejemplo, el siguiente script muestra el mensaje "Escriba el nombre de usuario" en árabe:

if (!($username)) { $msgTable.promptMsg }

Si Import-LocalizedData no encuentra un .psd1 archivo que coincida con el valor de $PSUIculture, el valor de $msgTable no se reemplaza y la llamada a $msgTable.promptMsg muestra las cadenas en-US de reserva.

Ejemplos

En este ejemplo se muestra cómo se usan las características de internacionalización de scripts en un script para mostrar un día de la semana a los usuarios en el idioma establecido en el equipo.

A continuación se muestra una lista completa del archivo de script Sample1.ps1.

El script comienza con una sección Datos denominada Day ($Day) que contiene un ConvertFrom-StringData comando. La expresión enviada a ConvertFrom-StringData es una cadena aquí que contiene los nombres de día en la referencia cultural predeterminada de la interfaz de usuario, en-US, en pares clave-valor. El ConvertFrom-StringData cmdlet convierte los pares clave-valor de la cadena aquí en una tabla hash y, a continuación, lo guarda en el valor de la $Day variable.

El Import-LocalizedData comando importa el contenido del .psd1 archivo en el directorio que coincide con el valor de la $PSUICulture variable automática y, a continuación, lo guarda en la $Day variable, reemplazando los valores de $Day que se definen en la sección Datos.

Los comandos restantes cargan las cadenas en una matriz y las muestran.

$Day = Data {
#culture="en-US"
ConvertFrom-StringData -StringData @'
    messageDate = Today is
    d0 = Sunday
    d1 = Monday
    d2 = Tuesday
    d3 = Wednesday
    d4 = Thursday
    d5 = Friday
    d6 = Saturday
'@
}

Import-LocalizedData -BindingVariable Day

#Build an array of weekdays.
$a = $Day.d0, $Day.d1, $Day.d2, $Day.d3, $Day.d4, $Day.d5, $Day.d6

# Get the day of the week as a number (Monday = 1).
# Index into $a to get the name of the day.
# Use string formatting to build a sentence.

"{0} {1}" -f $Day.messageDate, $a[(Get-Date -UFormat %u)] | Out-Host

Los .psd1 archivos que admiten el script se guardan en subdirectorios del directorio de script con nombres que coinciden con los $PSUICulture valores.

A continuación se muestra una lista completa de .\de-DE\sample1.psd1:

# culture="de-DE"
ConvertFrom-StringData @'
    messageDate = Heute ist
    d0 = Sonntag
    d1 = Montag
    d2 = Dienstag
    d3 = Mittwoch
    d4 = Donnerstag
    d5 = Freitag
    d6 = Samstag
'@

Como resultado, al ejecutar Sample.ps1 en un sistema en el que el valor de $PSUICulture es de-DE, la salida del script es:

Heute ist Freitag