Language templates

[rebelinux]

Is your feature request related to a problem? Please describe.

It would be beneficial to add the option to generate the report in an available language. I don't know if it is achievable but maybe there could be a JSON file with the translations depending on the language. With the option for the user to create the JSON with the language of his choice based on a default english template

Describe the solution you'd like

• Command Example

  • New-AsBuiltReport -Report VMware.SRM -Target 192.168.5.2 -Format Word -Credential $cred (-Language French)

• Section Example

  • Section -Style Heading1 "$(Protection Groups JSON Variable)" {}

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

[alagoutte]

Hi,

I like the idea too @tpcarman do you have an idea for make this ?

[tpcarman]

I'm currently experimenting with how support for other languages could potentially be implemented for AsBuiltReport.

❗ This is not a commitment to adding this feature, I am simply working to determine if it would be feasible.

[tpcarman]

@baukeplugge has raised a PR to introduce language templates to the VMware vSphere report. I'd like to discuss the possibility of introducing this to the Core module instead to provide functionality for all reports. @rebelinux @alagoutte let me know what you guys think. I'll provide further feedback once I have had a good look through it.

[baukeplugge]

As from what I understood from powershell, the private function should remain private and within the module only. So we have to create a public translation function. like Get-AsBuiltTranslation or something.
This would be easy to implement. Only we need to decide the naming convention of the variable strings.
in my opinion we have message, those are almost always related to the product and you have keywords, like Name,Description and category etc. those will be generic.

So maybe we can create sub groups within the json, the same as in the config json.

• Generic
• Product specific like VMware.vSphere or Nutanix

and what will happen when the chosen language does not have the requested keyword. Will it fallback to english?

[rebelinux]

Looks good to me.

It would also be needed an option to change the language of the content in AsBuiltReport.Core.Style.ps1.

Example:

1. Author:
2. Date:
3. Version:
4. Table of Content
5. Etc

# Add Report Name
Paragraph -Style Title $ReportConfig.Report.Name

if ($AsBuiltConfig.Company.FullName) {
    # Add Company Name if specified
    BlankLine -Count 1
    Paragraph -Style Title2 $AsBuiltConfig.Company.FullName
    BlankLine -Count $LineCount
} else {
    BlankLine -Count ($LineCount + 1)
}
Table -Name 'Cover Page' -List -Style Borderless -Width 0 -Hashtable ([Ordered] @{
        'Author:' = $AsBuiltConfig.Report.Author
        'Date:' = (Get-Date).ToLongDateString()
        'Version:' = $ReportConfig.Report.Version
    })
PageBreak

if ($ReportConfig.Report.ShowTableOfContents) {
    # Add Table of Contents
    TOC -Name 'Table of Contents'
    PageBreak
}

The idea of providing a framework in the AsBuiltReport.Core and having each report owner provide the ability to translate its content through the json file would be the best option in my opinion.

An English file would be the master template that could perhaps be exported so that the user can translate the content into their preferred language.

I have seen a similar concept in the vCheck project.

https://github.com/alanrenouf/vCheck-vSphere/blob/master/Lang/en-US/vCheck.psd1

[tpcarman]

My initial thoughts are that we create the JSON structure similiar to the report config JSON so that it aligns more to the structure of the report.

{
    "Message": {
        "MessageURL": "Please refer to www.asbuiltreport.com for more detailed information about this project.",
        "MessageIssues": "Issues or bug reporting: https://github.com/AsBuiltReport/AsBuiltReport.VMware.vSphere/issues",
        "MessageDocumentation": "Documentation: https://github.com/AsBuiltReport/AsBuiltReport.VMware.vSphere",
        "MessageUpdate": "Do not forget to update your report configuration file after each new version release.",
        "MessageInstalledVersion": "The current installed version of AsBuiltReport.VMware.vSphere is ",
        "MessageNewVersion": "The latest version of AsBuiltReport.VMware.vSphere available is ",
        "MessageUpdateInstruction": "Run 'Update-Module -Name AsBuiltReport.VMware.vSphere -Force' to install the latest version.",
        "MessageConnecting": "Connecting to vCenter Server ",
        "MessagevCenterPrivilegesCheck": "Checking vCenter user privileges.",
        "MessagevCenterPrivilegesError": "Unable to obtain vCenter user privileges.",
        "MessageVMLookup": "Creating VM lookup hashtable.",
        "MessageVMHostLookup": "Creating VMHost lookup hashtable.",
        "MessageDatastoreLookup": "Creating Datastore lookup hashtable.",
        "MessageVDPortGroupLookup": "Creating VDPortGroup lookup hashtable.",
        "MessageEVCLookup": "Creating EVC lookup hashtable.",
        "MessageVUM": "Checking for VMware Update Manager Server.",
        "MessageVXRail": "Checking for VxRail Manager Server.",
        "MessageSRM": "Checking for VMware Site Recovery Manager Server.",
        "MessageNSX": "Checking for VMware NSX-T Manager Server.",
        "MessageVcenterAdv": "Collecting advanced settings of vCenter Server ",
        "MessageInfoLevel": "vCenter InfoLevel set at "
    },
    "Keyword": {
        "Keyword_Description": "Description",
        "Keyword_IPAddress": "IP Address",
        "Keyword_MACAddress": "MAC Address",
        "Keyword_Capacity": "Capacity",
        "Keyword_Mailsettings": "Mail Settings",
        "Keyword_MailSender": "Mail Sender",
        "Keyword_SMTPServer": "SMTP Server",
        "Keyword_SMTPPort": "SMTP Port",
        "Keyword_HistoricalStatistics": "Historical Statistics",
        "Keyword_Licensing": "Licensing",
        "Keyword_Total": "Total",
        "Keyword_Used": "Used",
        "Keyword_LicenseKey": "License Key",
        "Keyword_Available": "Available"
    },
    "Cluster": {
        "ConfigDetails_vCenter": "The following sections detail the configuration of vCenter Server ",
        "ClusterDetailsIntro_vCenter": "The following sections detail the configuration of vSphere HA/DRS clusters managed by vCenter Server ",
        "ClusterDetails_vCenter": "The following table details the configuration for cluster ",
        "ClusterDetailsHA_vCenter": "The following section details the vSphere HA configuration for cluster ",
        "ClusterDetailsProactiveHA_vCenter": "The following section details the Proactive HA configuration for cluster ",
        "ClusterDetailsDRS_vCenter": "The following table details the vSphere DRS configuration for cluster ",
        "ClusterDetailsPermissions_vCenter": "The following table details the permissions assigned to cluster ",
        "ClusterDetailsResourcePool_vCenter": "The following sections detail the configuration of resource pools managed by vCenter Server ",
        "ClusterDetailsHosts_vCenter": "The following sections detail the configuration of VMware ESXi hosts managed by vCenter Server ",
        "ClusterDetailsHostsHardware_vCenter": "The following section details the host hardware configuration for "
    },
    "ResourcePool": {

    },
    "VMHost": {
        "HostsConfigDetails_vCenter": "The following section details the host system configuration for ",
        "HostsStorage_vCenter": "The following section details the host storage configuration for ",
        "HostsStorageAdapters_vCenter": "The following section details the storage adapter configuration for ",
        "HostsNetwork_vCenter": "The following section details the host network configuration for ",
        "HostsNetworkPhysical_vCenter": "The following section details the physical network adapter configuration for ",
        "HostsNetworkCDP_vCenter": "The following section details the CDP information for ",
        "HostsNetworkLLDP_vCenter": "The following section details the LLDP information for ",
        "HostsNetworkVMkernel_vCenter": "The following section details the VMkernel adapter configuration for ",
        "HostsNetworkvSwitch_vCenter": "The following section details the standard virtual switch configuration for ",
        "HostsSecurity_vCenter": "The following section details the host security configuration for ",
        "HostsVM_vCenter": "The following section details the virtual machine configuration for ",
        "HostsNetworkDVS_vCenter": "The following sections detail the configuration of distributed switches managed by vCenter Server "
    },
    "Network": {

    },
    "vSAN": {

    },
    "Datastore": {

    },
    "DSCluster": {

    },
    "VM": {

    },
    "VUM": {

    }
}

If structured like above, a standard prefix might not be necessary? Not sure. But if it was, then prefixes like Message, Keyword, Heading etc might be the way to go?

I don't speak multiple languages so I don't know how far we need to go with this?

Here's a couple of questions for you:

1. Is it necessary to replace every English word, including those in verbose output, cover page, tables etc?
2. What is the preferred/best selection method for the language?
3. Should the report language be defined in the report JSON config?

"Report": {
        "Name": "VMware vSphere As Built Report",
        "Version": "1.0",
        "Status": "Released",
        "ShowCoverPageImage": true,
        "ShowTableOfContents": true,
        "ShowHeaderFooter": true,
        "ShowTableCaptions": true,
        "Language": "en-GB"
    }

I'll keep thinking and playing with this idea.

[baukeplugge]

i'll test to see if I can change the function to use the structured JSON input. I think that would be much clearer to read the file.
I think the translations can be done with google translate. Maybe we can start with the following languages:

• English (default)
• Dutch (my native language)

Maybe French,Spanish and German?
Some keywords dont need to be translated for the dutch language, we use the same words in some cases.
The current function is reading the language from the config file. but the config file is populated later then some of the words that need to be translated. So maybe we need to use a powershell parameter?

[baukeplugge]

I have updated the functions and made the get-asbuiltTranslation public:

function Get-AsBuiltTranslation {
<#
.SYNOPSIS
Get asbuilt translation.
.DESCRIPTION

.LINK
    https://github.com/AsBuiltReport/AsBuiltReport.Core
.LINK
    https://www.asbuiltreport.com/user-guide/new-asbuiltconfig/
#>
[CmdletBinding()]
param (
[Parameter(
        Mandatory = $true,
        HelpMessage = 'The category of the translation (e.g., "Message", "Keyword")'
    )]
    [ValidateNotNullOrEmpty()]
    [String] $Category,
	[Parameter(
        Mandatory = $true,
        HelpMessage = 'The word for which translation is required'
    )]
    [ValidateNotNullOrEmpty()]
    [String] $Key,
	[Parameter(
        Mandatory = $true,
        HelpMessage = 'The product (e.g., "vCenter")'
    )]
    [ValidateNotNullOrEmpty()]
    [String] $Product
)

# Load translations for the globally set language
$translations = Load-Translations -Language "en"

# Load English translations as a fallback
$englishTranslations = Load-Translations -Language "en"

# Check if translations are loaded and if the specified product, category, and key exist
if ($translations -and $translations.$Product -and $translations.$Product.$Category -and $translations.$Product.$Category.PSObject.Properties[$Key]) {
    # Return the translation for the specified key within the category and product
    return $translations.$Product.$Category.$Key
} elseif ($englishTranslations -and $englishTranslations.$Product -and $englishTranslations.$Product.$Category -and $englishTranslations.$Product.$Category.PSObject.Properties[$Key]) {
    # Return the English translation as a fallback
    Write-Warning "Translation for key '$Key' in category '$Category' for product '$Product' not found. Using English fallback."
    return $englishTranslations.$Product.$Category.$Key
} else {
    # Output a warning if the key is not found in any translations
    Write-Warning "Translation for key '$Key' in category '$Category' for product '$Product' not found in any language."
    return $Key  # Return the key itself if no translation is found
}

}

I have placed this in the .core code and placed the load-translations in the private and got those loaded aswell.

Function to load translations from a JSON file

function Load-Translations {
param (
[string]$Language # The language code for which translations are needed
)

# Construct the file path to a JSON file containing translations for the specified language
$filePath = Join-Path -Path (Join-Path -Path $PSScriptRoot -ChildPath "../../languages") -ChildPath "$Language.json"

# Check if the translation file exists
if (Test-Path $filePath) {
    # Read the content of the JSON file as a raw string
    $jsonContent = Get-Content -Path $filePath -Raw
    # Convert the JSON string into a PowerShell object and return it
    return $jsonContent | ConvertFrom-Json
} else {
    # Output an error message if the file does not exist
    Write-Error "Translation file for language '$Language' not found."
    return $null  # Return null if the file is not found
}

}

i have adjusted the json like this
{
"vCenter":{
"Messages":{
"ConfigDetails_vCenter":"The following sections detail the configuration of vCenter Server ",
"ClusterDetailsIntro_vCenter":"The following sections detail the configuration of vSphere HA/DRS clusters managed by vCenter Server ",
"ClusterDetails_vCenter":"The following table details the configuration for cluster ",
"ClusterDetailsHA_vCenter":"The following section details the vSphere HA configu"
}
}
}

to get a translation: Get-AsBuiltTranslation -Product "vCenter" -Category "messages" -Key "ConfigDetails_vCenter"
So first you choose your product, then the category and last the string to be translated.

this is working fine.

[alagoutte]

Hi,

Sorry guy for delay... but great news about some update about translation

Is it necessary to replace every English word, including those in verbose output, cover page, tables etc?
i think only needed the report not need for verbose .

What is the preferred/best selection method for the language?
Should` the report language be defined in the report JSON config?
Check the language system ? and override with Json config ?

not sure about json, is the better for translation file, often the translator guy are not really dev guy...
May be look already existing translation file (like ts for qt, or po file...) and it will be possible to use some translation platform (like transifex)

also for translation, there is often problem with number (display number or plural it can be complicated ^^)