AsBuiltReport
Replies: 15 comments 21 replies
-
|
Hi, I like the idea too @tpcarman do you have an idea for make this ? |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
@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. |
Beta Was this translation helpful? Give feedback.
-
|
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. So maybe we can create sub groups within the json, the same as in the config json.
and what will happen when the chosen language does not have the requested keyword. Will it fallback to english? |
Beta Was this translation helpful? Give feedback.
-
|
Looks good to me. It would also be needed an option to change the language of the content in AsBuiltReport.Core.Style.ps1. Example:
# 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 |
Beta Was this translation helpful? Give feedback.
-
|
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 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:
"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. |
Beta Was this translation helpful? Give feedback.
-
|
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.
Maybe French,Spanish and German? |
Beta Was this translation helpful? Give feedback.
-
|
I have updated the functions and made the get-asbuiltTranslation public: function Get-AsBuiltTranslation { } 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 filefunction Load-Translations { } i have adjusted the json like this to get a translation: Get-AsBuiltTranslation -Product "vCenter" -Category "messages" -Key "ConfigDetails_vCenter" this is working fine. |
Beta Was this translation helpful? Give feedback.
-
|
Hi, Sorry guy for delay... but great news about some update about translation
not sure about json, is the better for translation file, often the translator guy are not really dev guy... also for translation, there is often problem with number (display number or plural it can be complicated ^^) |
Beta Was this translation helpful? Give feedback.
-
|
any news about this subject ? |
Beta Was this translation helpful? Give feedback.
-
|
@rebelinux I see you have implemented language support within your Diagrammer tool. Can you provide any insights as to how we could do the same for AsBuiltReport? |
Beta Was this translation helpful? Give feedback.
-
|
In progress! |
Beta Was this translation helpful? Give feedback.
-
Anything you can reveal or share? I'd like to keep this as an open discussion with the direction we take. The chosen path needs to be consistent for all reports, and while I don't have any multi-language requirements myself, I want to ensure that all the report modules can utilise the feature in the same way. |
Beta Was this translation helpful? Give feedback.
-
|
I haven't implemented something like this before so I asked ChatGPT and Claude for their recommendations, and both recommended using PowerShell's Built-in internationalization features. Using PowerShell's Built-in Internationalization FeaturesPowerShell has excellent built-in support for internationalization. Here's the recommended approach: 1. Use the Data Section PatternCreate a Data section in your script that separates text strings from code instructions, using ConvertFrom-StringData to convert text strings into dictionary-like hash tables. $Messages = Data {
# culture="en-US" (default)
ConvertFrom-StringData @'
ReportTitle = Infrastructure Report
GeneratingReport = Generating report for {0}...
ErrorConnecting = Error connecting to {0}: {1}
CompletedSuccessfully = Report completed successfully
'@
}2. Implement .psd1 Language FilesStore translated text strings in .psd1 files in language-specific subdirectories using the format 3. Use Import-LocalizedDataUse Import-LocalizedData to dynamically retrieve translated strings based on the user's UI culture ($PSUICulture): # Import localized strings
Import-LocalizedData -BindingVariable Messages -ErrorAction SilentlyContinue
# Use in your code
Write-Host ($Messages.GeneratingReport -f $TargetServer)Implementation Strategy for AsBuiltReportModule Structure ApproachFor a project like AsBuiltReport, I recommend:
Example Implementation:function Get-LocalizedString {
param(
[string]$Key,
[object[]]$Arguments,
[string]$Culture = $PSUICulture
)
if (-not $script:LocalizedStrings) {
# Try to import localized data
Import-LocalizedData -BindingVariable LocalizedStrings -ErrorAction SilentlyContinue
# If import failed, use default English strings
if (-not $script:LocalizedStrings) {
$script:LocalizedStrings = Data {
ConvertFrom-StringData @'
ReportTitle = Infrastructure Report
GeneratingReport = Generating report for {0}...
# ... more default strings
'@
}
}
}
$string = $script:LocalizedStrings[$Key]
if ($Arguments) {
return ($string -f $Arguments)
}
return $string
}Best Practices for AsBuiltReport:
Language File Structure:# en-US/AsBuiltReport.psd1
ConvertFrom-StringData @'
Report.Title = Infrastructure Report
Report.Generating = Generating report for {0}...
Report.Complete = Report generation completed successfully
Error.Connection = Unable to connect to {0}: {1}
Error.Authentication = Authentication failed for {0}
Table.ServerName = Server Name
Table.IPAddress = IP Address
'@This approach provides a clean, maintainable solution that follows PowerShell best practices and will scale well as you add more languages to the AsBuiltReport project. The built-in PowerShell internationalization features are robust and well-supported across different PowerShell versions. Feasibility of implementing internationalization using PowerShell's built-in i18n featuresCurrent Architecture AnalysisThe AsBuiltReport modules follow a consistent structure:
Feasibility Assessment: HIGHLY FEASIBLEThe internationalization approach I outlined would work very well with the AsBuiltReport architecture for several reasons: ✅ Advantages
🎯 Implementation StrategyPhase 1: Core Foundation
Phase 2: Module-by-Module ImplementationEach module would follow this pattern: # In each module's .psm1
$script:LocalizedStrings = $null
function Initialize-AsBuiltReportLocalization {
Import-LocalizedData -BindingVariable script:LocalizedStrings -ErrorAction SilentlyContinue
if (-not $script:LocalizedStrings) {
$script:LocalizedStrings = Data {
ConvertFrom-StringData @'
Section.vCenter = vCenter Server
Section.Cluster = Cluster Configuration
Table.Name = Name
Table.Version = Version
Health.Critical = Critical
Health.Warning = Warning
'@
}
}
}Phase 3: Language File Structure📊 Impact AnalysisLow Risk Changes Needed:
Minimal Breaking Changes:
🔧 Specific Examples from the CodebaseLooking at the VMware vSphere module, strings like these would be localized: Current: Section -Style Heading2 'vCenter Server Configuration' {
# ...
}Localized: Section -Style Heading2 (Get-AsBuiltLocalizedString 'Section.vCenterConfiguration') {
# ...
}🌍 Multi-Module CoordinationThe beauty of this approach is that each module can be internationalized independently while sharing common localization infrastructure from
📈 Recommended Implementation Order
ConclusionThe PowerShell internationalization approach is not only feasible but ideal for the AsBuiltReport project architecture. The modular structure, consistent patterns, and existing configuration-driven approach make this a natural fit. The implementation would be evolutionary rather than revolutionary, maintaining backward compatibility while adding powerful new capabilities. |
Beta Was this translation helpful? Give feedback.
-
|
Nice... need to try ! |
Beta Was this translation helpful? Give feedback.
-
|
there's a lot to get up to speed with here (at least for me) but with the help of AI, it certainly seems a little easier and possible. I'll keep tweaking the prompts but the responses seem to be on the right track. I'm interested to hear your thoughts on this approach. AsBuiltReport Multilingual SupportExecutive SummaryThis document outlines a comprehensive approach for implementing multilingual support across AsBuiltReport modules using PowerShell's built-in internationalization features. The proposed solution maintains backward compatibility, follows PowerShell best practices, and scales effectively across all AsBuiltReport modules. Background & GoalsCurrent State
Objectives
Recommended Approach: Structured Content ObjectsAfter evaluating multiple approaches, Structured Content Objects provides the optimal balance of functionality, maintainability, and PScribo compatibility. Why This Approach?✅ PScribo Native: Maps directly to PScribo's formatting capabilities Technical Implementation1. Core ArchitectureModule StructureCore Localization Functions# Central localization function for all modules
function Get-AsBuiltLocalizedString {
param(
[Parameter(Mandatory)]
[string]$Key,
[Parameter()]
[object[]]$Arguments,
[Parameter()]
[string]$ContentType = 'Simple'
)
# Use the language set during New-AsBuiltReport initialization
$culture = if ($script:ReportLanguage) { $script:ReportLanguage } else { 'en-US' }
# Implementation handles different content types with fallback to en-US
}
# Module initialization with language parameter from AsBuiltReport.Core
function Initialize-AsBuiltReportLocalization {
param(
[string]$Culture = 'en-US',
[string]$ModuleName
)
# Load appropriate language files for the specific module
# Always fallback to en-US if requested language unavailable
# No JSON configuration changes needed
}2. Content Structure ExamplesSimple Strings (Basic Labels, Titles, Messages)# en-US/AsBuiltReport.VMware.vSphere.psd1
ConvertFrom-StringData @'
Section.vCenter = vCenter Server Configuration
Section.Cluster = Cluster Configuration
Table.Name = Name
Table.Version = Version
Health.Critical = Critical
Health.Warning = Warning
Error.Connection = Unable to connect to {0}: {1}
Report.Generating = Generating report for {0}...
'@Structured Content (Complex Sections, Health Checks)# en-US/HealthChecks.psd1
@{
'vSAN.CapacityUtilization' = @{
Title = 'vSAN Capacity Utilization Check'
Description = 'This health check validates that vSAN clusters maintain optimal storage capacity utilization levels.'
Details = @{
Purpose = 'Identifies vSAN clusters with storage capacity utilization over 75% to prevent performance degradation and ensure adequate growth capacity.'
Thresholds = @(
'Warning: 75-90% capacity utilization'
'Critical: >90% capacity utilization'
)
Impact = 'High capacity utilization can lead to performance issues, failed VM operations, and inability to handle node failures.'
Remediation = @(
'Add additional storage capacity to the vSAN cluster'
'Review and archive unnecessary VM snapshots'
'Implement storage policies to optimize space efficiency'
'Consider enabling deduplication and compression'
)
}
Recommendation = 'Maintain vSAN capacity utilization below 75% for optimal performance and resilience.'
}
}Complex Multi-Section Content# en-US/ContentTemplates.psd1
@{
'SecurityOverview' = @{
Title = 'Security Configuration Overview'
Introduction = 'This section provides a comprehensive analysis of security configurations across your infrastructure.'
Sections = @(
@{
Heading = 'Network Security'
Style = 'Heading2'
Content = 'Analysis of network-level security controls and segmentation.'
Items = @(
'Network Security Group (NSG) configuration and effectiveness'
'Firewall rule analysis and optimization opportunities'
'Network segmentation and micro-segmentation implementation'
'Public IP exposure assessment and risk analysis'
)
ItemStyle = 'Bullet'
},
@{
Heading = 'Identity and Access Management'
Style = 'Heading2'
Content = 'Evaluation of identity controls and access management policies.'
Items = @(
'Multi-factor authentication coverage and enforcement'
'Privileged access management implementation'
'Service account security and lifecycle management'
'Role-based access control (RBAC) effectiveness'
)
ItemStyle = 'Bullet'
}
)
Summary = 'Regular security assessment ensures adherence to best practices and regulatory requirements.'
}
}3. Helper FunctionsContent Rendering Functions# Render structured content objects to PScribo format
function Write-AsBuiltStructuredContent {
param(
[Parameter(Mandatory)]
[hashtable]$ContentObject
)
Section -Name $ContentObject.Title -Style Heading1 {
if ($ContentObject.Introduction) {
Paragraph -Text $ContentObject.Introduction
BlankLine
}
foreach ($section in $ContentObject.Sections) {
Section -Name $section.Heading -Style $section.Style {
if ($section.Content) {
Paragraph -Text $section.Content
BlankLine
}
if ($section.Items) {
Write-AsBuiltContentItems -Items $section.Items -Style $section.ItemStyle
}
}
}
if ($ContentObject.Summary) {
BlankLine
Paragraph -Text $ContentObject.Summary -Bold
}
}
}
function Write-AsBuiltContentItems {
param(
[string[]]$Items,
[ValidateSet('Bullet', 'Numbered', 'Plain')]
[string]$Style = 'Bullet'
)
switch ($Style) {
'Bullet' {
foreach ($item in $Items) {
Paragraph -Text "• $item"
}
}
'Numbered' {
for ($i = 0; $i -lt $Items.Count; $i++) {
Paragraph -Text "$($i + 1). $($Items[$i])"
}
}
'Plain' {
foreach ($item in $Items) {
Paragraph -Text $item
}
}
}
}4. Language Parameter IntegrationAsBuiltReport.Core Enhancement# Enhanced New-AsBuiltReport function with optional Language parameter
function New-AsBuiltReport {
[CmdletBinding()]
param(
[Parameter(Mandatory)]
[String] $Report,
[Parameter(Mandatory)]
[String] $Target,
# Other existing parameters...
[Parameter()]
[ValidateSet('en-US', 'de-DE', 'fr-FR', 'es-ES', 'ja-JP')]
[String] $Language = 'en-US'
)
# Set culture for the report generation session
$script:ReportLanguage = $Language
# Initialize localization for the specific report module
Initialize-AsBuiltReportLocalization -Culture $Language -ModuleName $Report
# Continue with existing report generation logic...
}Usage Examples# Default behavior (English) - no breaking changes
New-AsBuiltReport -Report VMware.vSphere -Target 'vcenter-01.local'
# Generate German report
New-AsBuiltReport -Report VMware.vSphere -Target 'vcenter-01.local' -Language 'de-DE'
# Generate French report
New-AsBuiltReport -Report VMware.vSphere -Target 'vcenter-01.local' -Language 'fr-FR'Implementation PhasesPhase 1: Foundation (AsBuiltReport.Core)
Phase 2: Pilot Module (VMware vSphere)
Phase 3: Core Modules Expansion
Phase 4: Community Localization
Phase 5: Advanced Features
Benefits & ImpactFor Users
For Contributors
For Project
Migration StrategyBackward Compatibility
Gradual Implementation
Contributor GuidelinesFor Module Developers
For Translators
Success Metrics
Next Steps
Questions for Discussion
|
Beta Was this translation helpful? Give feedback.
-
Beta Was this translation helpful? Give feedback.
-
|
I've started with translations within the Core module. I've added a What I have implemented so far uses PowerShell's culture to set the language for the console input and outputs. This provides a user with all prompts and messages in their native/preferred language, as set within their OS. While the There is a language mapping function to map and resolve main languages to variants, which will also fail back to I've uploaded what I have created so far in the multilingual-support branch so you can check it out. I've just realised I need to correct the function of the style script though as this should use the Have a play and let me know what you think. You can submit PRs for any translation corrections if you like. For any ideas or changes to other functionality, please share here first before submitting a PR. |
Beta Was this translation helpful? Give feedback.
-
|
i make a quick review of french translation and it will look for use on next week on my module ! |
Beta Was this translation helpful? Give feedback.
-
@alagoutte Don't make any changes to the report modules yet! I'm still working through how that will work. My intention is that only a language folder structure will be required and possibly a JSON change, but please hold off until I have confirmed the changes. |
Beta Was this translation helpful? Give feedback.
-
|
i don't plan to try before some week ;-) (and i want to try to make some Diagram first ^^) |
Beta Was this translation helpful? Give feedback.
-
|
I've pushed the latest changes to the multilingual-support branch. At this point, no major changes are planned for the implementation, unless of course we uncover some major issues. You're welcome to test, provide feedback and open any pull requests for the core module if necessary. |
Beta Was this translation helpful? Give feedback.
-
We're almost ready for pre-release!The latest updates for AsBuiltReport.Core can be found here. @rebelinux kindly created a system resource report module for testing the new language functionality. The intent is to publish this module for testing and demo purposes, but for now you can find it here. A total of 28 language translations have been included with both modules.The next steps are to update the AsBuiltReport website documentation and begin on adding language translations to report modules. English UI
Spanish UI
|
Beta Was this translation helpful? Give feedback.
-
|
Website documentation updated and ready for launch 🚀 |
Beta Was this translation helpful? Give feedback.
-
|
Thanks ! |
Beta Was this translation helpful? Give feedback.
-
Website is updated and live, with notices that the feature is coming in the next release. 🥳 |
Beta Was this translation helpful? Give feedback.
-
|
I've now published
|
Beta Was this translation helpful? Give feedback.
-
|
|
Beta Was this translation helpful? Give feedback.
-
|
AsBuiltReport.Core v1.5.0 has been released which adds multilingual support 🍾 🎉 The AsBuiltReport website provides the relevant documentation, here, and here. While development of report modules is on-going, we are unable to provide a delivery timeline for adding language support to existing report modules. Please refer to the documentation with how you can assist to add language support to report modules. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
-
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
Section Example
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.
Beta Was this translation helpful? Give feedback.
All reactions