ShouldPersistCommentsOnExport

ShouldPersistCommentsOnExport

#Overview

name: ShouldPersistCommentsOnExport

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ShouldPersistCommentsOnExport is to control whether user comments in existing PO (Portable Object) files should be preserved during the localization export process. This setting is primarily used in the localization and internationalization systems of Unreal Engine 5.

This setting variable is relied upon by the Localization module of Unreal Engine 5, specifically in the localization configuration and export processes. It’s used in the LocalizationConfigurationScript and UserGeneratedContentLocalization namespaces, as well as in the InternationalizationExportCommandlet.

The value of this variable is typically set in the localization target settings. It’s defined as a boolean property in the FLocalizationExportingSettings struct, which is part of the localization target types.

This variable interacts with other localization export settings, such as ShouldAddSourceLocationsAsComments and the POFormat (Portable Object Format) settings.

Developers must be aware that this setting is particularly useful when working with third-party localization services that store editor or translator notes in the PO format’s comment fields. Enabling this option will preserve these comments during the export process, which can be crucial for maintaining context and communication in the localization workflow.

Best practices when using this variable include:

  1. Enable it when working with external localization teams or services that rely on PO file comments for additional context or notes.
  2. Consider the trade-off between preserving comments and file size/complexity, especially for large projects.
  3. Use in conjunction with ShouldAddSourceLocationsAsComments to provide comprehensive context for translators.
  4. Ensure that the localization export configuration is consistent across different parts of the project to avoid confusion or inconsistencies in the exported files.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/Localization/EngineOverrides_Export.ini:30, section: [GatherTextStep0]

Location: <Workspace>/Projects/Lyra/Config/Localization/Game_Export.ini:30, section: [GatherTextStep0]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/Localization/Private/LocalizationConfigurationScript.cpp:737

Scope (from outer to inner):

file
namespace    LocalizationConfigurationScript
function     FLocalizationConfigurationScript GenerateExportTextConfigFile

Source code excerpt:

				ConfigSection.Add(TEXT("POFormat"), POFormatName.ToString());

				ConfigSection.Add(TEXT("ShouldPersistCommentsOnExport"), Target->Settings.ExportSettings.ShouldPersistCommentsOnExport ? TEXT("true") : TEXT("false"));
				ConfigSection.Add(TEXT("ShouldAddSourceLocationsAsComments"), Target->Settings.ExportSettings.ShouldAddSourceLocationsAsComments ? TEXT("true") : TEXT("false"));
			}
			
			Script.AddGatherTextStep(0, MoveTemp(ConfigSection));
		}

#Loc: <Workspace>/Engine/Source/Developer/Localization/Private/UserGeneratedContentLocalization.cpp:389

Scope (from outer to inner):

file
namespace    UserGeneratedContentLocalization
function     bool ExportLocalization

Source code excerpt:

				ConfigSection.Add(TEXT("POFormat"), StaticEnum<EPortableObjectFormat>()->GetNameStringByValue((int64)ExportOptions.UGCLocDescriptor.PoFormat));

				ConfigSection.Add(TEXT("ShouldPersistCommentsOnExport"), TEXT("true"));

				GatherConfig.AddGatherTextStep(GatherStepIndex++, MoveTemp(ConfigSection));
			}

			// Write config
			{

#Loc: <Workspace>/Engine/Source/Developer/Localization/Public/LocalizationTargetTypes.h:312

Scope (from outer to inner):

file
function     FLocalizationExportingSettings

Source code excerpt:

		: CollapseMode(ELocalizedTextCollapseMode::IdenticalTextIdAndSource)
		, POFormat(EPortableObjectFormat::Unreal)
		, ShouldPersistCommentsOnExport(false)
		, ShouldAddSourceLocationsAsComments(true)
	{
	}

	/* How should we collapse down text when exporting to PO? */
	UPROPERTY(config, EditAnywhere, Category = "Collapsing", AdvancedDisplay)

#Loc: <Workspace>/Engine/Source/Developer/Localization/Public/LocalizationTargetTypes.h:327

Scope: file

Source code excerpt:

	/* Should user comments in existing PO files be persisted after export? Useful if using a third party service that stores editor/translator notes in the PO format's comment fields. */
	UPROPERTY(config, EditAnywhere, Category = "Comments")
	bool ShouldPersistCommentsOnExport;

	/* Should source locations be added to PO file entries as comments? Useful if a third party service doesn't expose PO file reference comments, which typically store the source location. */
	UPROPERTY(config, EditAnywhere, Category = "Comments")
	bool ShouldAddSourceLocationsAsComments;
};

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Commandlets/InternationalizationExportCommandlet.cpp:182

Scope (from outer to inner):

file
function     int32 UInternationalizationExportCommandlet::Main

Source code excerpt:

	{
		bool bShouldPersistComments = false;
		GetBoolFromConfig(*SectionName, TEXT("ShouldPersistCommentsOnExport"), bShouldPersistComments, ConfigPath);

		// Load the manifest and all archives
		FLocTextHelper LocTextHelper(SourcePath, ManifestName, ArchiveName, NativeCultureName, CulturesToGenerate, GatherManifestHelper->GetLocFileNotifies(), GatherManifestHelper->GetPlatformSplitMode());
		LocTextHelper.SetCopyrightNotice(GatherManifestHelper->GetCopyrightNotice());
		{
			FText LoadError;