MS_ResourceFiles - NetDevInfraWGinOSSConsortium/NetDevInfraWiki GitHub Wiki

リ゜ヌスファむル

抂芁

  • リ゜ヌスファむルマネヌゞリ゜ヌスファむルは、

    • 文字列や画像などのリ゜ヌス情報を Key-Value で保持する、
      拡匵子が .resources たたは .resx のファむルのこずである。

    • いろいろな蚀語のリ゜ヌスファむルを甚意するず、
      倚蚀語察応のアプリケヌションを䜜成できる。

    • アセンブリ・ファむル(dll, exe)に含められる。

  • 参考

補足2 ぀の甚途: リ゜ヌスファむルには、
性質の異なる 2 ぀の甚途が混圚しおいるため、
先に切り分けおおくず読みやすい。

① 埋め蟌みリ゜ヌス画像・アむコン・テキスト
     → 「1 ファむルにたずめお配垃したい」ずいう配眮の話

② ロヌカラむズ倚蚀語察応
     → 「蚀語ごずに文蚀を差し替えたい」ずいう囜際化の話

本ペヌゞは①を特城で、②を倚蚀語察応で扱っおいる。
実務で䞻に䜿われるのは②である
①は珟圚、埋め蟌みリ゜ヌスEmbeddedResourceを盎接䜿う方が倚い。

特城

仕組み

  • *.resx ファむル ず *.designer.csvbファむルから成る。

  • *.resx ファむル
    埋め蟌たれたリ゜ヌスずしお埋め蟌たれる XML ファむル。

  • *.designer.csvbファむル
    埋め蟌たれたリ゜ヌスを読み取るコヌドが自動生成される。

補足ビルド時の流れ: .resx がどう倉換されるかを
抌さえおおくず、埌述のサテラむト アセンブリの話が理解しやすい。

Strings.resx      ──(ResGen)──> Strings.resources ──┐
Strings.ja.resx   ──(ResGen)──> Strings.ja.resources ──
                                                       ↓
  Strings.resources    → 本䜓アセンブリMyApp.dllに埋め蟌み
  Strings.ja.resources → [AL.exe](MS_NuGetMSB3086) で
                          ja\MyApp.resources.dllサテラむトを生成

Strings.Designer.cs ← ResXFileCodeGenerator が自動生成
  ResourceManager 経由でアクセスする厳密に型指定されたプロパティ

AL.exe が芋぀からないず MSB3086 になるのは、
このサテラむト アセンブリ生成の段階である。

メッセヌゞ等の隠蔜化が可胜

  • アセンブリ・ファむル(dll, exe)に含められるため、改ざんされにくい。

  • ただし、リ゜ヌスファむルの修正を反映するには再ビルドが必芁。
    ※ ILSpy 等の逆アセンブルツヌルにおリ゜ヌスファむルの内容が
    抜出されるこずは防げない

補足隠蔜の目的で䜿わない: 原文自身が泚蚘しおいる通り、
リ゜ヌスは容易に抜出できるILSpy で䞞芋え。

リ゜ヌスファむルが提䟛するのは
  ・「うっかり線集される」こずの防止蚭定ファむルず違い、倖に出ない
  ・配垃物の䞀䜓化
であっお、
  ・秘密情報の保護
ではない。

接続文字列・API キヌをリ゜ヌスに入れおはならない。
それらは .NET Core config の
ナヌザヌ シヌクレット / 環境倉数 / Key Vault に眮く。

たた、「再ビルドが必芁」ずいう性質は運甚䞊の制玄でもある。
文蚀を運甚䞭に倉えたい堎合は、
DB や倖郚ファむルから読む仕組み埌述のIStringLocalizer の
カスタム実装等を怜蚎する。

実行䞭の差し替えが可胜

移行メモ衚珟: 「実行䞭の差し替えが可胜」は、
サテラむト アセンブリja\MyApp.resources.dllを
差し替えられる、ずいう意味である
本䜓アセンブリに埋め蟌んだ既定リ゜ヌスは差し替えられない。

ReleaseAllResources() でキャッシュを解攟すれば
次回のアクセスで再読み蟌みされるが、
ファむルがロックされおいる堎合は差し替え自䜓ができない点に泚意する。

文字列以倖も扱うこずが可胜

リ゜ヌスファむルに画像などのバむナリファむルを文字列ず同様に含めるこずが可胜である。
この際、BASE64 ゚ンコヌドされた文字列が resx ファむルに栌玍される。

補足バむナリは別ファむル参照が望たしい: .resx に
BASE64 で盎接埋め蟌むず、

  • .resx が肥倧し、差分が読めなくなるGit で扱いにくい
  • マヌゞ競合が解決䞍胜になる

ずいう問題が出る。
.resx からは「ファむルぞの盞察パス」で参照する圢
Visual Studio の既定動䜜にしおおく方がよい。

<data name="Logo" type="System.Resources.ResXFileRef, System.Windows.Forms">
  <value>Resources\logo.png;System.Drawing.Bitmap, System.Drawing</value>
</data>

**単に「DLL に画像を埋め蟌みたい」**だけなら、
.resx を䜿わず EmbeddedResource で足りる。

<ItemGroup>
  <EmbeddedResource Include="Assets\logo.png" />
</ItemGroup>
using var s = Assembly.GetExecutingAssembly()
    .GetManifestResourceStream("MyApp.Assets.logo.png");

倚蚀語化察応が可胜

カルチャを䜿甚し、察応したリ゜ヌスファむルから
情報を取埗するこずで文蚀や、UI 芁玠の倚蚀語察応が可胜ずなる詳现は埌述。

詳现

䜜成方法

リ゜ヌスファむルの䜜成方法には䞋蚘の様なものがある。

Visual Studio 䞊でリ゜ヌスファむルを䜜成、線集する

  • Visual Studio でリ゜ヌスを䜜成、線集できる。

  • 通垞 Key-Value だが、画像 / アむコン / テキスト・ファむルも远加できる。

  • Visual Studio でリ゜ヌス䞭に改行コヌドを入れる方法

リ゜ヌス䜜成画面にお

ShiftEnterキヌ

を抌䞋するず改行コヌドを挿入できる。

.NET プログラムからリ゜ヌスファむルを䜜成する方法

リ゜ヌスファむルを䜜成する API が甚意されおいる。

テキストファむルからリ゜ヌスファむルを䜜成する方法

.txt ファむルからリ゜ヌスファむルを䜜成する Resgen.exe が甚意されおいる。

補足翻蚳のやり取りは XLIFF / CSV で: 実務では、
翻蚳䌚瀟や珟地担圓者ずファむルをやり取りする必芁がある。
.resx をそのたた枡すのは扱いにくいため、
䞭間圢匏に倉換するのが䞀般的である。

圢匏 甹途
XLIFF 翻蚳業界の暙準圢匏。倚くの翻蚳ツヌルが察応
CSV / Excel 手軜。瀟内翻蚳向け
Multilingual App Toolkit Visual Studio 拡匵。.resx ↔ XLIFF

キヌの呜名芏則を先に決めおおくこずが重芁で、
埌から䞀括倉換するのは非垞に手間がかかる。

䜿甚方法

リ゜ヌスファむルの䜿甚方法には䞋蚘の様なものがある。

Visual Studio 䞊で既存のリ゜ヌスファむルを開く

  • *.resx ファむルを開く。

  • カスタム・ツヌルを蚭定する。

    • ダブルクリックしおデザむナの DDL から Internal or Public を遞択する。
    • プロパティ・グリッドのカスタム・ツヌルに以䞋を蚭定する。
      • ResXFileCodeGeneratorInternal
      • PublicResXFileCodeGeneratorPublic

  • これにより、

    • *.resx ファむルず、
    • *.designer.csvbファむルが

グルヌプ化される。

移行メモ衚蚘: 原文の「デザむナの DDL」は
**ドロップダりン リストDDL**を指すず読めるが、
デヌタベヌスの DDL ず玛らわしいため泚蚘しおおく
実際にはリ゜ヌス ゚ディタヌ䞊郚の「アクセス修食子」の
ドロップダりンを指す。

Internal、Public の遞定基準ず利甚方法

  • Internal
    ゚ントリ・アセンブリ ※1 内でのみ䜿甚する堎合コチラを遞択する。
    ※ 1: 珟圚の AppDomain の゚ントリポむントを含むアセンブリ

  • Public

補足MissingManifestResourceException の原因: 原文が
参考に挙げおいるこの䟋倖は、リ゜ヌス呚りで最頻出のトラブルである。

原因の倧半は「リ゜ヌス名の解決に倱敗しおいる」

  期埅される名前: <既定の名前空間>.<フォルダ>.<ファむル名>
  䟋:             MyApp.Resources.Strings

【よくあるずれ】
  ・プロゞェクトの既定の名前空間を倉曎した
  ・.resx を別フォルダに移動した
  ・ビルド アクションが「埋め蟌たれたリ゜ヌス」になっおいない
  ・ラむブラリ偎ずアプリ偎でルヌト名前空間が違う原文の指摘

確認方法:

// 実際に埋め蟌たれおいるリ゜ヌス名を列挙する
foreach (var n in Assembly.GetExecutingAssembly().GetManifestResourceNames())
    Console.WriteLine(n);

ResourceManager を自分で䜜る堎合は、
この名前を正確に枡す必芁がある。

var rm = new ResourceManager("MyApp.Resources.Strings",
                             typeof(SomeTypeInThatAssembly).Assembly);

.NET プログラムからリ゜ヌスファむルを䜿甚する方法

  • *.designer.csvbに実装された、
    プロパティ・プロシヌゞャ経由でリ゜ヌスにアクセスできる。

  • リ゜ヌスファむルを䜿甚する API が甚意されおいる。

  • 参考

制限事項

  • リ゜ヌスの名前に "="(半角むコヌル) を含めるこずができたせん。
  • リ゜ヌスの倀に LF(Line Feed) を含めるこずができたせん。

移行メモ制限の背景: これらは
.txt 圢匏Resgen.exe が扱う name=value 圢匏の制限であり、
.resxXMLでは該圓しない
.resx なら = も LF も栌玍できる。
原文のテキストファむルからリ゜ヌスファむルを䜜成する方法に
察応する泚意事項ず読むのが劥圓である。

倚蚀語察応

スレッド毎に保持しおいる CurrentUICulture に蚭定されおいる
カルチャを䜿甚しお、
察応したリ゜ヌスファむルから情報を取埗するこずで文蚀や、
UI 芁玠の倚蚀語察応が可胜ずなる。

補足CurrentCulture ず CurrentUICulture は別物: 混同されやすいが、
圹割が明確に分かれおいる。

CurrentCulture CurrentUICulture
甹途 曞匏日付・数倀・通貚・䞊べ替え リ゜ヌスの遞択文蚀
䟋 1,234.56 / 2026/08/19 Strings.ja.resx を遞ぶ
蚭定元 OS の地域蚭定 OS の衚瀺蚀語 
// 日本語 UI・米囜匏の数倀曞匏、ずいう組み合わせもあり埗る
Thread.CurrentThread.CurrentUICulture = new CultureInfo("ja-JP");  // 文蚀
Thread.CurrentThread.CurrentCulture   = new CultureInfo("en-US");  // 曞匏

**「文蚀は日本語なのに日付が 8/19/2026 になる」**ずいった珟象は、
この 2 ぀を取り違えおいるこずが原因である。

リ゜ヌスの構造

  • ファむル名ず拡匵子の間にカルチャ名を挿入しお
    各カルチャ向けのリ゜ヌスファむルを䜜成する。

  • 䞋䜍カルチャ甚のリ゜ヌスファむルには差分のみ定矩可胜。

R1.resx　　　　　　　既定カルチャ甚リ゜ヌスファむル
├R1.ja.resx　　　　　日本語甚リ゜ヌスファむル
├R1.en.resx　　　　　英語甚リ゜ヌスファむル
├R1.zh-Hans.resx　　簡䜓字䞭囜語甚リ゜ヌスファむル
└R1.zh-Hant.resx　　繁䜓字䞭囜語甚リ゜ヌスファむル

R2.resx　　　　　　　既定カルチャ甚リ゜ヌスファむル
├R2.ja-JP.resx　　　日本語(日本)甚リ゜ヌスファむル
└R2.en-US.resx　　　英語(米囜)甚リ゜ヌスファむル

補足「既定カルチャ」に䜕を入れるか: 拡匵子なしの R1.resx に
䜕語を入れるかは、蚭蚈刀断である。

方針 利点 欠点
英語を既定にする 囜際的に無難。未翻蚳でも読める 日本語のみの案件では冗長
日本語を既定にする 囜内案件では自然 未察応蚀語で日本語が出る
キヌ名だけ入れる 未翻蚳が䞀目で分かる 事故時に衚瀺が厩壊する

NeutralResourcesLanguage 属性で
「既定リ゜ヌスは䜕語か」を明瀺しおおくず、
その蚀語ではサテラむトの探玢をスキップするため起動が速くなる。

[assembly: NeutralResourcesLanguage("ja-JP",
           UltimateResourceFallbackLocation.MainAssembly)]

フォヌルバック機胜

リ゜ヌスファむルのフォヌルバック機胜ずは

  • 䜿甚するリ゜ヌスファむルをシステムが刀断するこずを指す。
  • CurrentUICulture のカルチャず䞀臎するリ゜ヌスファむルが
    存圚しない堎合、芪カルチャ甚のリ゜ヌスファむルを順に怜玢する。

補足探玢の順序: 具䜓的には次の順に探す。

CurrentUICulture = "zh-Hant-TW" の堎合

  ① zh-Hant-TW\MyApp.resources.dll   特定カルチャ
  ② zh-Hant\MyApp.resources.dll      䞭立カルチャ
  ③ zh\MyApp.resources.dll           芪
  ④ 本䜓アセンブリの既定リ゜ヌス      最終フォヌルバック

  ④ にも無ければ MissingManifestResourceException

䞋䜍カルチャで差分のみ定矩できる原文の蚘述のは、
この段階的な探玢によるものである。

R1.resx      : Yes / No / Cancel / Save / Delete
R1.ja.resx   : はい / いいえ / キャンセル      ← Save/Delete は未定矩
  → 日本語環境では Save/Delete は英語のたた衚瀺される

フォヌルバックのカスタマむズ

  • Parent プロパティで䞊䜍のカルチャを取埗可胜なので単玔なアルゎリズムで䜜成可胜。
  • たた、メッセヌゞを蚀語毎に甚意するのであれば
    TwoLetterISOLanguageName プロパティで 2 階局目の倀を取埗するこずが可胜なため、
    その倀で分岐すれば良い。

参考

サテラむトアセンブリ

補足配眮ず配垃の泚意点: サテラむト アセンブリは
アプリの実行フォルダ盎䞋のカルチャ名フォルダに眮かれる。

bin\Release\net8.0\
  MyApp.dll
  ja\MyApp.resources.dll
  en\MyApp.resources.dll
  zh-Hans\MyApp.resources.dll

実務䞊の泚意:

論点 内容
配垃挏れ カルチャ フォルダのコピヌ忘れで「英語になる」
䞍芁な蚀語 SatelliteResourceLanguages で絞れるサむズ削枛
単䞀ファむル発行 サテラむトも埋め蟌たれる.NET 5+
NuGet で配る NuGetパッケヌゞの開発ず公開 の Localized Package 
<!-- 日本語ず英語だけを出力する他蚀語のサテラむトを䜜らない -->
<PropertyGroup>
  <SatelliteResourceLanguages>ja;en</SatelliteResourceLanguages>
</PropertyGroup>

NuGet パッケヌゞが倚蚀語のサテラむトを持っおいるず
出力が膚らむため、䞊蚘で絞るのは実甚的な最適化である。

UI の倚蚀語察応

リ゜ヌスファむルを䜿甚するこずで、UI の倚蚀語察応が可胜である。

Windows FormsずASP.NET Web Formsで
実装の方法が異なる。

Windows Formsの堎合

ASP.NETの堎合

WPF/Silverlightの堎合

補足ASP.NET Core の方匏最新化: ASP.NET Core では
IStringLocalizer / IViewLocalizer ずいう抜象を通す方匏に
倉わっおいる。

// Program.cs
builder.Services.AddLocalization(o => o.ResourcesPath = "Resources");
builder.Services.AddControllersWithViews()
    .AddViewLocalization()
    .AddDataAnnotationsLocalization();

var cultures = new[] { "ja", "en" };
app.UseRequestLocalization(new RequestLocalizationOptions()
    .SetDefaultCulture("ja")
    .AddSupportedCultures(cultures)
    .AddSupportedUICultures(cultures));
public class HomeController(IStringLocalizer<HomeController> L) : Controller
{
    public IActionResult Index() { ViewData["Title"] = L["Welcome"]; ... }
}
@inject IViewLocalizer L
<h1>@L["Welcome"]</h1>

本ペヌゞずの䞻な違い:

.NET Framework ASP.NET Core
アクセス Designer.cs の型付きプロパティ IStringLocalizerDI
キヌが無いずき 䟋倖 キヌ名がそのたた返る萜ちない
カルチャの決定 スレッドに蚭定 RequestLocalizationMiddlewareURL / Cookie / ヘッダヌ
差し替え サテラむト DLL IStringLocalizer を自䜜DB / JSON も可

**「キヌが無くおも萜ちない」**のは実務䞊倧きな違いで、
未翻蚳の項目があっおも画面は衚瀺される
代わりに、未翻蚳の怜出は別途行う必芁がある。

たた、IStringLocalizer を自䜜すれば
DB や JSON から文蚀を読めるため、
本ペヌゞのメッセヌゞ等の隠蔜化が可胜で述べた
「再ビルドが必芁」ずいう制玄を回避できる。

参考

Microsoft Learn

.NET Tips (VB.NET,C#...)

Tags: 移行, .NET開発, 囜際化察応

このWikiは「Open棟梁Project」,「OSSコン゜ヌシアム 開発基盀郚䌚」によっお運営されおいたす。

⚠ **GitHub.com Fallback** ⚠