sobre la Internacionalización del Guión

Breve descripción

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

Descripción larga

Las funciones de internacionalización de scripts de PowerShell le permiten brindar un mejor servicio a los usuarios de todo el mundo al mostrar ayuda y mensajes de usuario en su idioma.

Las funciones de internacionalización de scripts consultan la cultura de la interfaz de usuario del sistema operativo durante la ejecución, importan las cadenas de texto traducidas apropiadas y las muestran al usuario. La sección Datos le permite almacenar cadenas de texto separadas del código para que puedan identificarse y extraerse fácilmente. Un nuevo cmdlet, ConvertFrom-StringData, convierte cadenas de texto en tablas hash similares a un diccionario para facilitar la traducción.

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

Una sección de 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 utilizado en el sistema para elementos como la fecha, la hora y la moneda. La variable $PSUICulture almacena el nombre del idioma de la interfaz de usuario utilizado 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 a un diccionario para facilitar la traducción. Para obtener más información, consulte ConvertFrom-StringData.
Un nuevo tipo de archivo, .psd1, que almacena cadenas de texto traducidas. Los archivos .psd1 se almacenan en subdirectorios específicos del idioma del directorio del script.
Un cmdlet, Import-LocalizedData, que importa cadenas de texto traducidas para un idioma específico 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, consulte Importar datos localizados.

La sección de datos: almacenamiento de cadenas predeterminadas

Utilice una sección de 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 separada. Si incluye comentarios, los comentarios deben estar en líneas separadas.

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

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

$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: almacenamiento de cadenas traducidas

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

<language>-<region>

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

Por ejemplo, si el script World.ps1 está almacenado en el directorio C:\Scripts, crearía una estructura de directorio 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 archivo World.psd1 en el subdirectorio de-DE del directorio del script podría incluir la siguiente declaración:

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

De manera similar, el archivo World.psd1 en el subdirectorio ar-SA del directorio del script podría incluir la siguiente declaració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, utilice el cmdlet Import-LocalizedData.

Import-LocalizedData encuentra el valor de la variable automática $PSUICulture e importa el contenido de los archivos <script;-name>.psd1 en el subdirectorio que coincida con el valor $PSUICulture. Luego, guarda el contenido importado en la variable especificada por el valor del parámetro BindingVariable.

Import-LocalizedData -BindingVariable msgTable

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

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

Luego, importa las cadenas de texto árabe del archivo a la variable $msgTable, reemplazando cualquier cadena predeterminada que pueda estar definida en la sección Datos del script World.ps1.

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

Por ejemplo, la siguiente secuencia de comandos muestra el mensaje "Ingrese su nombre de usuario" en árabe:

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

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

Ejemplos

Este ejemplo muestra cómo se utilizan las funciones de internacionalización de secuencias de comandos en una secuencia de comandos para mostrar un día de la semana a los usuarios en el idioma configurado en la computadora.

La siguiente es una lista completa del archivo de script Sample1.ps1.

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

El comando Import-LocalizedData importa el contenido del archivo .psd1 en el directorio que coincide con el valor de la variable automática $PSUICulture y luego lo guarda. en la variable $Day, reemplazando los valores de $Day que están definidos 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 archivos .psd1 que admiten el script se guardan en subdirectorios del directorio del script con nombres que coinciden con los valores $PSUICulture.

La siguiente es 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, cuando ejecuta Sample.ps1 en un sistema en el que el valor de $PSUICulture es de-DE, la salida del script es:

Heute ist Freitag

Ver también

about_Data_Sections
about_Automatic_Variables
about_Hash_Tables
about_Quoting_Rules
Import-LocalizedData
ConvertFrom-StringData