CulturesToStage

CulturesToStage

#Overview

name: CulturesToStage

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

It is referenced in 3 C++ source files. Also referenced in 2 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of CulturesToStage is to specify which localization cultures should be included in the packaging process of an Unreal Engine 5 project. This setting variable is used to control which language and regional variants of the game’s content are prepared for distribution.

This setting variable is primarily used by the packaging and cooking subsystems of Unreal Engine 5. Based on the callsites, it’s utilized in the following modules:

  1. DeveloperToolSettings: Where the variable is defined in the ProjectPackagingSettings class.
  2. UnrealEd: Specifically in the CookCommandlet and PlayLevelViaLauncher functionalities.

The value of this variable is set in the project’s configuration files, as indicated by the UPROPERTY(config) attribute in the variable declaration. It can be edited through the Project Settings interface in the Unreal Editor, under the Packaging category.

CulturesToStage interacts with other localization-related variables, such as LocalizationTargetsToChunk, which determines which localization targets should be split into separate chunks during the cooking process.

Developers should be aware that:

  1. This variable directly impacts the size of the packaged game, as each included culture adds localized assets to the build.
  2. It affects the cooking time, as more cultures require more data to be processed.
  3. The cultures specified here should match the languages supported by the game to ensure all necessary localizations are included.

Best practices when using this variable include:

  1. Only include cultures that are actually supported and tested in the game to avoid unnecessary bloat.
  2. Coordinate with the localization team to ensure all required cultures are included.
  3. Consider using this in conjunction with chunked cooking for large projects to optimize download sizes for different regions.
  4. Regularly review and update this list as the project’s localization support evolves.
  5. Test the packaged build with different culture configurations to ensure proper localization loading and fallback behavior.

#Setting Variables

#References In INI files

<Workspace>/Engine/Config/BaseGame.ini:109, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:125, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:126, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:127, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:128, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:129, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:130, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:131, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:132, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:133, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:134, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:135, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:136, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:137, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:138, section: [/Script/UnrealEd.ProjectPackagingSettings]
<Workspace>/Projects/Lyra/Config/DefaultGame.ini:139, section: [/Script/UnrealEd.ProjectPackagingSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/DeveloperToolSettings/Classes/Settings/ProjectPackagingSettings.h:464

Scope (from outer to inner):

file
class        class UProjectPackagingSettings : public UObject

Source code excerpt:

	/** Cultures whose data should be cooked, staged, and packaged. */
	UPROPERTY(config, EditAnywhere, Category=Packaging, AdvancedDisplay, meta=(DisplayName="Localizations to Package"))
	TArray<FString> CulturesToStage;

	/** List of localization targets that should be chunked during cooking (if using chunks) */
	UPROPERTY(config, EditAnywhere, Category=Packaging, AdvancedDisplay)
	TArray<FString> LocalizationTargetsToChunk;

	/** The chunk ID that should be used as the catch-all chunk for any non-asset localized strings */

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Commandlets/CookCommandlet.cpp:382

Scope (from outer to inner):

file
function     bool UCookCommandlet::CookByTheBook

Source code excerpt:

	else
	{
		CookCultures = PackagingSettings->CulturesToStage;
	}

	const bool bUseZenStore =
		!Switches.Contains(TEXT("SkipZenStore")) &&
		(Switches.Contains(TEXT("ZenStore")) || PackagingSettings->bUseZenStore);

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/PlayLevelViaLauncher.cpp:387

Scope (from outer to inner):

file
function     void UEditorEngine::StartPlayUsingLauncherSession

Source code excerpt:

		TArray<FString> IniMapSections;

		StartCookByTheBookInEditor(TargetPlatforms, CookedMaps, CookDirectories, GetDefault<UProjectPackagingSettings>()->CulturesToStage, IniMapSections);

		FIsCookFinishedDelegate &CookerFinishedDelegate = LauncherProfile->OnIsCookFinished();

		CookerFinishedDelegate.BindUObject(this, &UEditorEngine::IsCookByTheBookInEditorFinished);

		FCookCanceledDelegate &CookCancelledDelegate = LauncherProfile->OnCookCanceled();

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/AutomationTool/Scripts/CopyBuildToStagingDirectory.Automation.cs:490

				if (PlatformGameConfig != null)
				{
					PlatformGameConfig.GetArray("/Script/UnrealEd.ProjectPackagingSettings", "CulturesToStage", out CulturesToStage);
				}
			}

			// Error if no cultures have been provided.
			if (bMustExist && (CulturesToStage == null || CulturesToStage.Count == 0))
			{

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/Windows/AppXManifestGeneratorBase.cs:513

			List<string>? SelectedUECultureIds;
			string DefaultUECultureId;
			GameIni.GetArray("/Script/UnrealEd.ProjectPackagingSettings", "CulturesToStage", out SelectedUECultureIds);
			GameIni.GetString("/Script/UnrealEd.ProjectPackagingSettings", "DefaultCulture", out DefaultUECultureId);
			if (SelectedUECultureIds == null || SelectedUECultureIds.Count < 1)
			{
				Logger.LogError("At least one culture must be selected to stage.");
				return null;
			}