Dave Sexton

Hi,

As of the June 2007 CTP, where are all of the places that a localization option must be explicitly set in order to produce completely localized .chm and .HxS files

Here's the information that I have so far:

  1. Replace XML document(s) with localized content in the Content folder of the chosen Sandcastle presentation; e.g., Prototype, vs2005 or Hana.
  2. Replace XML document(s) in the Shared presentation's Content folder with localized content.
  3. Modify the value of the locale item in the shared_content.xml file.
  4. Set the locale value on the ResolveReferenceLinksComponent2 component in the sandcastle.config file (which doesn't work in the June 2007 CTP).

Do I have them all Is there any way to make this a bit simpler and more flexible

I think that having localizable text encapsulated in the Content XML documents was actually a nice design choice; however, having to replace the Shared documents as well adds some burden to the process. Then, of course, other changes must be made to various documents that shouldn't really be required as part of the default content of a presentation, which makes it somewhat difficult for a tool to add a localization feature that can also work well with custom presentation styles.

My goal is that I'd like to be able to allow users to choose from a list of locales and then build documentation for all of them in one process. But then there's this problem to worry about as well:

http://forums.microsoft.com/MSDN/ShowPost.aspx PostID=1979415&SiteID=1

Thanks,

Dave




Re: Developer Documentation and Help System Sandcastle: Localization

EWoodruff

There's a "language=" option in the CHM help project file (.hhp) created by the transformation, a LangId attribute on the HelpCollection element in the HxS project file (.hxc), and a LangId attribute on the HelpIndex element in the "_k" version of the ".hxk" index file. It looks like you got the rest. Since I don't think the Unicode issue with the CHM files will get fixed, I think it's something we just have to live with.

Eric





Re: Developer Documentation and Help System Sandcastle: Localization

Dave Sexton

Hi Eric,

It seems that the CHM project option may be superseded by the CHMBuilder's configuration file, for some scenarios.

As for the Help 2.x attributes, they're easy enough to control since those files aren't generated by an XSL transformation so I'm sure they won't be a problem. Thanks.

I assumed that the Unicode .chm issue isn't going to be fixed either, which is why I've been considering writing a completely managed help system from the ground up to target WinForms applications. After all, if you're deploying managed code to clients' systems anyway then why not have a managed help system as well Just an idea that I've been kicking around... Would you be interested in helping me to develop something like that for the community

- Dave






Re: Developer Documentation and Help System Sandcastle: Localization

EWoodruff

Hi Dave,

Yes, if you do start the project, let me know.

Eric





Re: Developer Documentation and Help System Sandcastle: Localization

Dave Sexton

Great! I have a bunch of ideas, so I'll get them down on file and contact you when I start up the project (maybe within a couple of weeks).

- Dave






Re: Developer Documentation and Help System Sandcastle: Localization

Dave Sexton

- I assume that CodePlex will contact you, but just in case this is a heads-up that you've been added to a new project:

www.codeplex.com/help

Big Smile

I'm surprised that I was able to get that!

- Dave






Re: Developer Documentation and Help System Sandcastle: Localization

EWoodruff

I didn't get notification but did see it the list of My Projects today. It looks like you've given it a lot of thought already Smile.

Eric





Re: Developer Documentation and Help System Sandcastle: Localization

Dave Sexton

Hi Eric,

It's been something in backlog for a few months now, but I don't have the time to do it all by myself Smile

You're a coordinator on the project, so please feel free to add/remove/modify whatever you'd like. My plan for now is to come up with some baseline features for a beta release and then open it up to discussion to the public. So let me know how you feel about my plans and the initial feature set that I outlined. Then, maybe in a few weeks we can start coding a steel thread for the first beta. FYI, all things are open for dicussion.

BTW, the name "Help!" was just something I came up with on the spot, so if you have a better idea please let me know!

- Dave






Re: Developer Documentation and Help System Sandcastle: Localization

Anand Raman - MSFT

We still do build CHMs for few projects and we have addressed the Unicode issues for CHMs built in East Asian languages. Here¡¯s a rough outline of it and I will post a blog:

1. The sources need to be in ANSI if the language¡¯s characters don¡¯t all map to Western-1252.

2. If you compile ANSI sources, the HTML help compiler assumes that the HTML codepage is your current system codepage. If you¡¯re set to EN-US like I am, the resulting CHM contains incorrect characters, unless I change my system settings (which requires a reboot).

To resolve this, one must:

1. Note the codepage in the source HTML (a META tag).

2. Re-encode all files in ANSI, using the appropriate code page.

3. Trick the OS in to stating its current codepage is something different than what it really is.

4. Compile.

Here¡¯s our solution:

1. Have ChmBuilder write the codepage as UTF-8 into the HTML as it generates them (they actually are UTF-8 at this point).

2. Re-encode the files using DBCSFix.exe. We are looking at shipping this as a part of Sandcastle. DBCS stands for Double Byte Charecter Set and we use this program to conver UTF-8 to ANSI . While doing so, substitute the actual codepage (e.g., big5) for what was initially written (UTF-8).

3. Wrap the call to HHC.exe in a call to MS APPLocale or SbAppLocale.exe, passing in the appropriate LCID.

Hope this helps.

Anand..






Re: Developer Documentation and Help System Sandcastle: Localization

Dave Sexton

Hi Anand,

Thanks for the reply.

I've never heard of the AppLocale utility. It sounds like it will help users to build .chm's with Unicode content more easily, when used in conjunction with the DBCSFix tool as well; however, it doesn't sound like an appropriate solution for a tool that is meant to automate Sandcastle. Asking users to download yet another separate utility is starting to seem a bit unreasonable, especially since this one is only for a workaround to a limitation in Microsoft's own software - HHC.exe.

It's time to update all of the tools to support Unicode so we can skip things like steps #2 and #3 - "Re-encode" and "Trick the OS" Smile

As Eric mentioned in this thread we don't expect HHC.exe to be updated, which is also why I'd like to see a managed solution now that is more flexible and with less bugs than .CHM - and I'm hoping that's exactly what we can accomplish with Help! Smile

- Dave






Re: Developer Documentation and Help System Sandcastle: Localization

Anand Raman - MSFT

I agree. However we will release DBCSFix with Monday's reelase and I will blog about the details on DBCSFix shortly. Howeer I do not expect any updates to CHM compiler to fix this issue.

Anand..






Re: Developer Documentation and Help System Sandcastle: Localization

Dave Sexton

Hi Anand,

That sounds good, thanks. I may try to implement the localization feature that I want using DBCSFix, so I'm interested in reading about it in your blog.

- Dave